docs: define example database subproject and defer implementation

CONTEXT.md

@@ -118,6 +118,15 @@ ritrovamento di una card tramite un collegamento non ne implica l'approvazione.
 espliciti, che contribuisce alla consultazione di contenuti pertinenti. La sua
 rimozione non comporta la cancellazione delle card collegate.
 
+## Esempi didattici
+
+**Example workspace** — Un workspace destinato alla pratica con ThothII, associato
+a dati di esempio, schema descritto ed Evidence curate, pronto per iniziare una sessione.
+
+**Practice question** — Una domanda di accompagnamento a un Example workspace,
+proposta come spunto per il percorso human in the loop e priva di soluzione attesa.
+_Avoid_: Solved Question, caso di valutazione del benchmark.
+
 ## Evidence
 
 **Context specialist** — La persona competente sul dominio che redige e cura il

README.md

@@ -34,11 +34,12 @@ for the executed consolidation and the inventory of historical sources retained
 
 ## Docker Compose and installation
 
-For a fresh installation, follow the complete manual procedure in
+For a fresh installation, follow the guided terminal procedure in
 [Italian](docs/install/standalone-manual-it.md) or
-[English](docs/install/standalone-manual-en.md). Configure protected files first;
-then run the documented build, explicit migrations and startup commands with the
-same installation descriptor and Compose project. There is no installer or launcher.
+[English](docs/install/standalone-manual-en.md). The single
+`tht setup --complete` command validates protected files, builds the images, runs
+Catalog migration, starts the stack and imports the configured workspace repository.
+There is no graphical installer or native launcher.
 
 The mandatory stack includes frontend, core, PostgreSQL catalog, Qdrant, Ollama
 and the embedding initializer. DWH and LLM endpoints remain external dependencies.

backend/src/operator-command.ts

@@ -16,12 +16,16 @@ import { loadSettings } from "./settings/settings-store.js";
 import { ThtRunner, type SessionRow } from "./tht/tht-runner.js";
 import { WorkspaceRegistry } from "./workspaces/registry.js";
 import { WorkspaceSecretStore } from "./workspaces/secret-store.js";
+import { createProductionWorkspaceDiagnoser } from "./workspaces/diagnostics.js";
+import { resolveCatalogRuntimeBinding } from "./catalog/runtime-binding.js";
+import { CatalogService } from "./catalog/service.js";
+import { validateOperationalWorkspace } from "./workspaces/schema.js";
 import { createCatalogRepository } from "./catalog/repository.js";
 import type { CatalogRepository } from "./catalog/types.js";
 
 type OperatorAction = "maintenance-activate" | "maintenance-deactivate" | "maintenance-status"
   | "session-inventory" | "workflow-doctor" | "workspace-integrity"
-  | "pi-test" | "effective-settings";
+  | "workspace-pull" | "workspace-test" | "pi-test" | "effective-settings";
 
 const lifecyclePrincipal: PrincipalContext = {
   issuer: "tht-operator-command",
@@ -119,6 +123,119 @@ async function workspaceIntegrity(config: AppConfig): Promise<{
   return { ready: true, ...integrity };
 }
 
+async function workspacePull(config: AppConfig): Promise<{
+  ready: boolean;
+  status: "succeeded" | "degraded";
+  branch: string;
+  head?: string;
+  degraded: boolean;
+}> {
+  const status = await new WorkspaceRegistry(config.workspaceRegistry).pull();
+  return {
+    ready: !status.degraded,
+    status: status.degraded ? "degraded" : "succeeded",
+    branch: status.branch,
+    ...(status.head ? { head: status.head } : {}),
+    degraded: status.degraded,
+  };
+}
+
+interface WorkspaceTestReport {
+  id: string;
+  status: "ready" | "failed";
+  database: "reachable" | "not_configured" | "failed";
+  diagnostics: string[];
+}
+
+async function workspaceTest(config: AppConfig): Promise<{
+  ready: boolean;
+  workspaces: WorkspaceTestReport[];
+}> {
+  if (!config.catalogDatabase) throw new Error("Catalog database is not configured");
+  const registry = new WorkspaceRegistry(config.workspaceRegistry);
+  const revisions = await registry.list();
+  const repository = createCatalogRepository(config.catalogDatabase);
+  try {
+    const secretStore = new WorkspaceSecretStore({
+      root: config.workspaceSecretStoreRoot,
+      runtimeRoot: config.workspaceSecretRuntimeRoot,
+      installationId: config.workspaceRegistry.installationId,
+    });
+    const catalogService = new CatalogService(
+      repository,
+      registry,
+      secretStore,
+      config.workspaceRegistry.secretRoots,
+      config.workspaceDiagnosticTimeoutMs,
+    );
+    const diagnose = createProductionWorkspaceDiagnoser(config.workspaceDiagnosticTimeoutMs, undefined, {
+      internalQdrantUrl: config.internalQdrantUrl,
+      internalEmbeddingUrl: config.internalEmbeddingUrl,
+      internalEmbeddingId: config.internalEmbeddingId,
+      internalEmbeddingModel: config.internalEmbeddingModel,
+      internalEmbeddingDimensions: config.internalEmbeddingDimensions,
+    });
+    const databases = await repository.list();
+    const reports: WorkspaceTestReport[] = [];
+    for (const revision of revisions) {
+      const diagnostics: string[] = [];
+      let workspace: ReturnType<typeof validateOperationalWorkspace>;
+      try {
+        workspace = validateOperationalWorkspace((await registry.read(revision.id)).workspace);
+      } catch {
+        reports.push({ id: revision.id, status: "failed", database: "not_configured", diagnostics: ["workspace_invalid"] });
+        continue;
+      }
+      const database = databases.find((candidate) => candidate.workspaceId === revision.id);
+      if (!database) {
+        reports.push({ id: revision.id, status: "failed", database: "not_configured", diagnostics: ["database_binding_missing"] });
+        continue;
+      }
+      let tested;
+      try {
+        tested = await catalogService.test(database);
+      } catch {
+        reports.push({ id: revision.id, status: "failed", database: "failed", diagnostics: ["database_unreachable"] });
+        continue;
+      }
+      if (!tested || tested.connectionStatus !== "reachable") {
+        reports.push({ id: revision.id, status: "failed", database: "failed", diagnostics: ["database_unreachable"] });
+        continue;
+      }
+      let lease: ReturnType<typeof resolveCatalogRuntimeBinding>;
+      try {
+        lease = resolveCatalogRuntimeBinding({
+          workspace,
+          database: tested,
+          environment: process.env,
+          secretRoots: config.workspaceRegistry.secretRoots,
+          secretStore,
+        });
+      } catch {
+        reports.push({ id: revision.id, status: "failed", database: "reachable", diagnostics: ["binding_missing"] });
+        continue;
+      }
+      try {
+        // CatalogService.test() above is the authoritative database probe and records its
+        // outcome. The remaining diagnoser pass checks Evidence and internal semantic services;
+        // skipping its legacy DWH probe avoids requiring a second response-shape contract for a
+        // REST health endpoint.
+        const result = await diagnose(lease.workspace, lease.bindings, { writeProbe: false, skipDwh: true });
+        diagnostics.push(...result.diagnostics.map((diagnostic) => diagnostic.code));
+        const ready = result.activatable;
+        reports.push({ id: revision.id, status: ready ? "ready" : "failed", database: "reachable", diagnostics });
+      } catch {
+        reports.push({ id: revision.id, status: "failed", database: "reachable", diagnostics: ["connector_unavailable"] });
+      } finally {
+        lease.release();
+      }
+    }
+    return { ready: reports.length > 0 && reports.every((report) => report.status === "ready"), workspaces: reports };
+  } finally {
+    await repository.close?.();
+  }
+}
+
 export async function runOperatorAction(
   action: OperatorAction,
   config: AppConfig,
@@ -132,6 +249,8 @@ export async function runOperatorAction(
   if (action === "session-inventory") return await sessionInventory(config);
   if (action === "workflow-doctor") return await workflowDiagnostics(config);
   if (action === "workspace-integrity") return await workspaceIntegrity(config);
+  if (action === "workspace-pull") return await workspacePull(config);
+  if (action === "workspace-test") return await workspaceTest(config);
   const modelCatalog = loadRuntimeModelCatalog(config.modelCatalogFile);
   if (action === "effective-settings") {
     return effectiveSettings(config, loadSettings(config), modelCatalog);
@@ -146,6 +265,7 @@ async function main(): Promise<void> {
   if (!action || ![
     "maintenance-activate", "maintenance-deactivate", "maintenance-status", "session-inventory",
     "workflow-doctor", "workspace-integrity", "pi-test", "effective-settings",
+    "workspace-pull", "workspace-test",
   ].includes(action)) throw new Error("invalid operator action");
   const result = await runOperatorAction(action, loadConfig(process.env));
   process.stdout.write(`${JSON.stringify(result)}\n`);

backend/test/operator-command.test.ts

@@ -36,6 +36,10 @@ vi.mock("../src/tht/tht-runner.js", () => ({
 
 vi.mock("../src/workspaces/registry.js", () => ({
   WorkspaceRegistry: class {
+    async pull() {
+      return { branch: "main", head: "a".repeat(40), ahead: 0, behind: 0, degraded: false };
+    }
+
     async listRetainedSnapshots() {
       return [{ snapshotPath: "/data/workspace-registry/snapshots/revision/workspace.yaml" }];
     }
@@ -98,3 +102,13 @@ test("workflow doctor gives schema-v4 runtime rendering a live Catalog repositor
   expect(fakes.releaseWorkspaceRuntime).toHaveBeenCalledOnce();
   expect(fakes.catalogRepository.close).toHaveBeenCalledOnce();
 });
+
+test("workspace pull exposes only safe Git status", async () => {
+  await expect(runOperatorAction("workspace-pull", config)).resolves.toEqual({
+    ready: true,
+    status: "succeeded",
+    branch: "main",
+    head: "a".repeat(40),
+    degraded: false,
+  });
+});

deploy/secrets/README.md

@@ -8,6 +8,11 @@ cp deploy/secrets/thothii.secrets.example deploy/secrets/thothii.secrets
 chmod 600 deploy/secrets/thothii.secrets
 ```
 
+For a normal local installation, `tht setup --complete` creates the active bundle at
+`deploy/local/secrets/thothii.secrets` and creates the two Catalog password files beside it. The
+generated `deploy/local/operator.env` contains only absolute paths to those files; never copy
+secret values into `operator.env`.
+
 The file uses strict `KEY=VALUE` lines (comments and blank lines are allowed). The supported
 installation keys are `THT_MODEL_API_KEY`, `THT_DWH_API_KEY`, `THT_CA`, `THT_SSL_CA`,
 `THT_OIDC_CLIENT_SECRET`, and `THT_AUTHENTIK_API_TOKEN`. Installation Model Catalog providers may
@@ -29,6 +34,11 @@ Session and metadata-generation runtimes read only the provider key named by
 credential reference, not their execution lifecycle. Pi-owned authentication remains available only
 to session-only built-in providers through `authentication.mode: pi_auth`.
 
+Workspace database credentials are intentionally not part of this global bundle. Configure each
+workspace's database binding, password/token, tunnel key and CA in Database Management; the
+installation stores those values in its encrypted workspace secret store. The workspace Git
+repository may declare database identity and Evidence, but must never contain these credentials.
+
 Do not add vector or embedding endpoint credentials to the bundle. Active operator manuals use
 internal Qdrant and Ollama services, so vector/embedding runtime endpoint secrets are not part of
 the supported installation contract.

docs/install/first-start.md

@@ -1,64 +1,63 @@
 # Install and first start
 
-Use one complete procedure for a fresh installation:
+Use the guided procedure for a fresh installation:
 
-- [Italian manual installation](standalone-manual-it.md)
-- [English manual installation](standalone-manual-en.md)
+- [Italian guided installation](standalone-manual-it.md)
+- [English guided installation](standalone-manual-en.md)
 
-Both cover macOS, Windows through Ubuntu WSL2, and Linux. They use a Gitea clone,
-protected local configuration and manual terminal commands, without an application
-installer or launcher. See their verification matrix for tests still pending.
+The procedure covers Windows through Ubuntu WSL2, macOS, and Linux including an Omarchy/Arch-like
+host. It uses the application clone, one installation secret bundle, protected repository
+credentials when needed, and a terminal command. No host Node.js, Python or Pi installation is
+required.
 
 ## What must be ready
 
-You need Docker with Compose, the host operator command `tht`, access to the workspace
-repository, and the credentials and network routes for the configured DWH and model
-providers. Pi runs inside the application runtime; no host Pi installation is needed.
+You need Docker with Compose v2, Git, Bash, curl, OpenSSL and shasum. You also need access to the
+workspace repository and the values supplied by its owner: repository URL/branch, DWH endpoint,
+database/schema, transport, credentials or certificates, Evidence credentials when applicable,
+and LLM provider/API-key information.
 
-The stack includes `frontend`, `core`, `catalog-db`, `qdrant`, `embedding`, plus the
-one-shot `embedding-model-init` and `catalog-migrate` services. DWH and generative-model
-endpoints remain separate installation settings.
+The workspace repository and the THothII application repository are different. A workspace
+descriptor may declare Evidence, but database passwords and installation bindings are stored in
+the installation Catalog, not in Git.
 
-Secrets, certificates, Pi authentication and endpoint bindings are protected local files.
-Do not commit them or copy the configuration of another machine unchanged.
+## One guided command
 
-## Follow the ordered procedure
+After cloning THothII, checking prerequisites and installing tht, run:
 
-The bilingual guides provide the exact commands for:
+~~~
+tht setup --complete --profile local --shell-mode full --shell-default-locale en
+~~~
 
-1. Cloning the selected revision and checking prerequisites.
-2. Bootstrapping the native host command.
-3. Preparing catalog passwords and using
-   `tht setup --profile local --shell-mode full --shell-default-locale en --configure-only`.
-4. Completing model, authentication and workspace credentials.
-5. Generating configuration, building images and explicitly running `catalog-migrate`.
-6. Starting the installation and checking health and readiness.
-
-Do not run setup alone as a substitute for that sequence. Migrations are not an
-implicit effect of backend startup or `tht start`. Do not mix this installation's
-descriptor/project with a different low-level Compose environment.
+The first run creates protected placeholders under deploy/local/secrets/. Fill the required
+credential files and rerun the same command. The command validates the local files and paths,
+renders Compose, builds the images, starts catalog-db, runs catalog-migrate, starts the full
+stack, and pulls/activates the workspace repository. Evidence source files declared by the
+workspace are imported during activation.
 
 For an already configured installation:
 
-```sh
+~~~
 tht --installation /absolute/path/thothii-installation.yaml status
 tht --installation /absolute/path/thothii-installation.yaml doctor --json
-```
+tht --installation /absolute/path/thothii-installation.yaml workspace test --json
+~~~
 
-`/health` checks application-process readiness. Doctor also checks configuration,
-workspace, workflow and Pi prerequisites; a healthy web page alone does not prove
-that a real database question can complete.
+doctor --json is the non-destructive general core test. workspace test also probes the configured
+database, Evidence, Qdrant and embedding service for every active workspace. It requires the
+workspace database to have been configured in Database Management first.
 
-## After startup
+## Installer-only completion
 
-Prepare [workspaces](../operations/workspaces.md), configure a database in
-[Database Management](../operations/database-management.md), and complete the functional
-checks in the installation guide before using real data.
+The installer must still decide which LLMs and API keys are approved, configure and test each
+workspace database, synchronize its schema, generate and consolidate descriptions, create Qdrant
+entries, review naming-based FK suggestions alongside schema FKs, and load the approved
+relationships. The final declaration of completeness requires green doctor and workspace test
+results plus one real natural-language question completed through final SQL.
 
-See [display mode and language](shell-and-language.md), [local authentication](authentication-local.md),
-[OIDC](authentication-oidc.md) and [model configuration](../general/pi-configuration.md)
-for later changes. Embedded portal integration is separate from a fresh standalone setup.
+Migrations are part of setup --complete. Do not mix this installation’s descriptor or volumes with
+a different Compose environment. Preserve the descriptor, credentials, Catalog and persistent
+volumes; do not use docker compose down --volumes as a routine stop.
 
-Use the installation's normal `tht start`, `tht stop` and diagnostic commands.
-Preserve its descriptor, credentials, database and persistent volumes; do not use
-`down --volumes` as a routine stop or upgrade.
+See the guides for the Windows/macOS/Linux prerequisite matrix, workspace repository explanation,
+secret layout and Gate A/Gate B acceptance checks.

docs/install/standalone-manual-en.md

@@ -1,324 +1,256 @@
-# Manual standalone installation
+# Guided 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.
+This is the fresh-machine installation procedure for THothII. THothII receives a natural-language
+question, queries an enterprise database read-only, and guides the user through SQL review. The
+core, PostgreSQL catalog, Qdrant, embedding service, and Pi run in Docker; Node.js, Python, and Pi
+are not required on the host.
 
-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.
+## Before you start: the two repositories
 
-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.
+There are two separate repositories:
 
-## Verification matrix
+1. the application repository cloned by the user:
+   https://git.tylconsulting.it/mptyl/ThothII.git;
+2. the workspace repository supplied by the curator/installer. It is not the THothII repository
+   and must not be cloned inside the application directory.
 
-| 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`) |
+The workspace repository normally contains:
 
-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.
+~~~
+thoth-workspaces.yaml
+<workspace-id>/workspace.yaml
+<workspace-id>/evidence/**       # when Evidence is declared
+~~~
 
-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.
+workspace.yaml contains workspace identity, language and optional Evidence source. By design it does
+not contain database passwords. Database identity, transport (PostgreSQL, REST, or tunnel), user,
+password, token and certificates are installation-local settings stored encrypted by the Catalog.
+This prevents credentials from being committed to the workspace repository.
 
-## Before you start
+## 0. Machine prerequisites
 
-You need:
+### Windows
 
-- 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.
+- Windows 10/11 with Docker Desktop running and the WSL2 backend enabled.
+- Ubuntu in WSL2, with Docker Desktop integration enabled for that distribution.
+- Git, Bash, curl, OpenSSL and shasum inside WSL2.
+- Do not install Node.js, Python or Pi on the host for this procedure.
 
-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.
+If WSL2 is not installed, use the company procedure or, in PowerShell:
 
-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.
+~~~
+wsl --install -d Ubuntu
+~~~
 
-Check the runtime before or immediately after cloning:
+Run all commands inside Ubuntu WSL2, in a Linux directory such as $HOME/src, not under /mnt/c.
+scripts/install-tht.ps1 exists for advanced native PowerShell scenarios; use WSL2 for the
+reproducible test.
 
-```sh
-docker version
+### macOS
+
+- Docker Desktop installed and running, with several GB free for images and the embedding model.
+- Git, Bash, curl, OpenSSL and shasum.
+- Intel and Apple Silicon Macs are supported when Docker Desktop supports the architecture
+  reported by the Docker server.
+- Do not install Node.js, Python or Pi on the host for this procedure.
+
+### Linux, including Omarchy
+
+- Git, Bash, curl, OpenSSL and shasum.
+- Docker Engine and the Docker Compose v2 plugin. On Omarchy, check first:
+
+~~~
+command -v docker
 docker compose version
+docker info
+~~~
+
+If Docker is missing, install Docker and Compose using the distribution-approved package procedure,
+then start the service. On an Arch-like distribution the typical route is:
+
+~~~
+sudo pacman -S docker docker-compose
+sudo systemctl enable --now docker
+sudo usermod -aG docker "$USER"
+~~~
+
+After adding the group, open a new session and repeat docker info. Node.js, Python and Pi are not
+needed on the host: they are in the Docker images.
+
+On every system run:
+
+~~~
+bash scripts/check-standalone-prerequisites.sh
 docker version --format '{{.Server.Arch}}'
-```
+~~~
 
-The last command must return `amd64`, `x86_64`, `arm64`, or `aarch64`.
+The architecture must be amd64, x86_64, arm64, or aarch64. You also need access to the
+application Gitea repository, the workspace repository URL/branch and credentials, container
+reachability to DWH/LLM endpoints, and the credentials, tokens or certificates associated with
+the databases.
 
-## 1. Clone a project revision
+## 1. What to clone
 
-Use the project repository on Gitea:
+Clone only the application:
 
-```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:
+Record the revision. tht setup --complete downloads the workspace repository into a persistent
+Docker volume using the URL, branch and transport supplied during setup.
 
-```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
+## 2. Install the terminal command
 
 From the clone root:
 
-```sh
+~~~
 bash scripts/check-standalone-prerequisites.sh
-export PATH="$HOME/.local/bin:$PATH"
+mkdir -p "$HOME/.local/bin"
 THT_INSTALL_DIRECTORY="$HOME/.local/bin" bash scripts/install-tht.sh
+export PATH="$HOME/.local/bin:$PATH"
 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.
+tht is the only native component to install. It builds the binary with Docker and orchestrates
+Compose; it is not a second application runtime.
 
-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. Prepare a few secrets and run complete setup
 
-## 3. Configure and start the local installation
+The first execution creates protected placeholders under deploy/local/secrets/ and stops if a
+required credential is missing. Fill in the requested files and rerun the same command; compatible
+configuration files are reused.
 
-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:
+~~~
+tht setup --complete --profile local --shell-mode full --shell-default-locale en
+~~~
 
-```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"
-```
+The setup asks only for information the computer cannot know:
 
-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 |
+| Request | What to provide |
 | --- | --- |
-| 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 |
+| Workspace repository | Data/configuration repository URL, not ThothII.git |
+| Branch | normally main |
+| Access | ssh with key and known_hosts, or https with credential file and CA |
+| DWH/LLM URL | endpoint without a token in the URL |
+| Local login | initial user and password requested by the prompt |
 
-The generated configuration is local and ignored by Git:
+The setup generates random Catalog passwords and writes their paths, never their values, to
+operator.env. It runs docker compose config, builds images, starts the Catalog, runs
+catalog-migrate, starts the stack, and pulls the workspace repository. The pull also activates
+declared Evidence; at minimum source files present in the workspace are materialized locally.
 
-```text
-deploy/local/thothii-installation.yaml
-deploy/local/operator.env
-deploy/local/auth/
-deploy/local/secrets/
-```
+### The file the user fills in
 
-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.
+The main file is:
 
-### Complete protected files
+~~~
+deploy/local/secrets/thothii.secrets
+~~~
 
-If setup created blank templates, enter the values with a local editor:
+Add only NAME=VALUE lines needed by modelCatalog and installation adapters, such as an LLM API key
+(DEEPSEEK_API_KEY, OPENAI_API_KEY, or the key declared by the catalog) and, when applicable,
+THT_DWH_API_KEY. Allowed names are documented in deploy/secrets/README.md. Never put tokens in
+URLs, the repository, or copied shell commands.
 
-```sh
-chmod 600 deploy/local/secrets/*
-"${EDITOR:-vi}" deploy/local/secrets/thothii.secrets
-```
+Two distinctions prevent common errors:
 
-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.
+- when the catalog uses pi_auth, the LLM token belongs in the Pi pi-auth.json file created by
+  setup; {} is only a placeholder and does not enable a model;
+- workspace database credentials (PostgreSQL password, REST API token, tunnel SSH key,
+  known_hosts, CA) do not belong in the workspace repository. Enter them per workspace in
+  Database Management, which stores them encrypted in the Catalog. The workspace declares
+  database/schema and transport; the installer must obtain the actual values from the database owner.
 
-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.
+A private workspace repository also needs the Git files required by its transport: an SSH key and
+known_hosts, or an HTTPS credential file and CA. These are transport files, not a second bundle to
+commit. To minimize manual files, use SSH with an already-authorized deploy key.
 
-Before starting, complete these additional configuration steps:
+## 4. Automatic checks and terminal tests
 
-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.
+Setup verifies files, permissions, descriptor, Compose, Docker, authentication, services, Pi and
+the workspace. After startup, run these commands at any time:
 
-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.
+~~~
+INSTALLATION="$PWD/deploy/local/thothii-installation.yaml"
+tht --installation "$INSTALLATION" doctor --json
+tht --installation "$INSTALLATION" workspace pull --json
+tht --installation "$INSTALLATION" workspace test --json
+~~~
 
-```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
-```
+workspace test checks, for every active workspace, database binding and credentials, Evidence,
+Qdrant, and the embedding service. It exits non-zero when the database binding is missing or a
+connection is unusable. Before running it, the installer must configure the database in Database
+Management: the workspace repository cannot contain the password by itself.
 
-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.
+doctor --json is the repeatable, non-destructive core verification. The final functional test must
+also open http://127.0.0.1:8080, sign in, and complete a real question through final SQL.
 
-## 4. Verify the installation
+## Activities only the installer can complete
 
-The descriptor generated for the default ID is:
+The procedure automates bootstrap, but it cannot invent enterprise decisions or authorizations.
+The installer must complete and record:
 
-```sh
-INSTALLATION="$(pwd -P)/deploy/local/thothii-installation.yaml"
-test -f "$INSTALLATION"
-bash scripts/verify-standalone-install.sh "$INSTALLATION"
-```
+1. usable LLMs, the modelCatalog, and linked API keys; then run tht pi test and tht doctor;
+2. database configuration, connection test, schema synchronization, and description generation;
+3. human consolidation of generated descriptions;
+4. Qdrant semantic entries through workspace preprocess run;
+5. naming-based FK suggestions as a complement to schema FKs, human review, and loading approved
+   relationships into Qdrant;
+6. recurring tht doctor --json and tht workspace test --json checks;
+7. one real question completed successfully without connection or model errors.
 
-The verifier is read-only: it runs `tht doctor --json` and `tht status` without restarting the
-stack, regenerating configuration, or printing secret contents.
+Configuration is complete only when all applicable activities are done, decisions are recorded, and
+the two terminal tests are green. The core is usable only after the real question, not merely
+because the frontend answers /health.
 
-### Gate A — platform smoke test on all three computers
+## Gate A and Gate B
 
-Record the following for each machine:
+### Gate A — platform
 
-```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:
+### Gate B — usability
 
-```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
-```
+tht --installation "$INSTALLATION" workspace test --json
+curl --fail --silent --show-error http://127.0.0.1:8080/health
+~~~
 
-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.
+Then run a real question and stop/restart with tht stop and tht start. Do not use docker compose
+down --volumes: it deletes the Catalog, sessions, Qdrant data and the embedding model.
 
 ## Quick diagnosis
 
-| Symptom | Check |
+| Symptom | Action |
 | --- | --- |
-| `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.
+| Docker Engine is not reachable | start Docker Desktop or systemctl and repeat docker info |
+| Omarchy cannot find docker | install Docker/Compose, enable the service and open a new session |
+| Windows sees Docker but Bash fails | use Ubuntu WSL2 and enable its Docker Desktop integration |
+| workspace pull fails | check URL, branch, key/credential file and known_hosts from the container |
+| workspace test reports a missing binding | configure database, token/password and CA in Database Management |
+| Pi is not ready | fill pi-auth.json or the key declared by modelCatalog, then run tht pi test |
 
 ## Related documents
 
 - [Install and first start](first-start.md)
-- [Shell and localization](shell-and-language.md)
 - [Workspace operations](../operations/workspaces.md)
-- `deploy/secrets/README.md` (runtime secrets)
+- [Database Management](../operations/database-management.md)
+- [Model configuration](../general/pi-configuration.md)
+- deploy/secrets/README.md
+
+Publishing images on Docker Hub and native DMG/MSI/AppImage installers remain later work: this
+procedure starts from the Gitea clone and does not require pre-published Docker Hub images.

docs/install/standalone-manual-it.md

@@ -1,329 +1,262 @@
-# Installazione manuale standalone
+# Installazione standalone guidata
 
 [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.
+Questa è la procedura per installare THothII da zero. THothII riceve una domanda in linguaggio
+naturale, interroga in sola lettura un database aziendale e accompagna l’utente nella revisione
+della SQL risultante. Il core, il catalogo PostgreSQL, Qdrant, il servizio di embedding e Pi vengono
+eseguiti in Docker; sul computer non servono Node.js, Python o Pi.
 
-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.
+## Prima di iniziare: i due repository
 
-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.
+Servono due repository distinti:
 
-## Matrice di verifica
+1. il repository dell’applicazione, che l’utente clona:
+   https://git.tylconsulting.it/mptyl/ThothII.git;
+2. il repository dei workspace, indicato dal curatore/installatore. Non è il repository di
+   THothII e non va clonato manualmente nella directory dell’applicazione.
 
-| 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`) |
+Il repository workspace contiene il catalogo e una directory per ogni workspace, normalmente:
 
-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.
+~~~
+thoth-workspaces.yaml
+<workspace-id>/workspace.yaml
+<workspace-id>/evidence/**       # se il workspace dichiara Evidence
+~~~
 
-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.
+Il file workspace.yaml descrive identità, lingua e, opzionalmente, la sorgente Evidence. Per scelta
+architetturale non contiene password del database. L’identità del database, il trasporto
+(PostgreSQL, REST o tunnel), username, password, token e certificati sono configurazione locale
+dell’installazione, conservata cifrata dal Catalog. Questo evita di committare credenziali nel
+repository workspace.
 
-## Cosa serve prima di iniziare
+## 0. Prerequisiti della macchina
 
-Servono:
+### Windows
 
-- 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.
+- Windows 10/11 con Docker Desktop avviato e backend WSL2 abilitato.
+- Ubuntu in WSL2, con integrazione Docker Desktop abilitata per quella distribuzione.
+- Git, Bash, curl, OpenSSL e shasum nella distribuzione WSL2.
+- Non installare Node.js, Python o Pi sull’host per questa procedura.
 
-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.
+In PowerShell, se WSL2 non esiste ancora, usare la procedura aziendale oppure:
 
-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.
+~~~
+wsl --install -d Ubuntu
+~~~
 
-Verificare il runtime prima del clone o subito dopo:
+Eseguire poi tutti i comandi dentro Ubuntu WSL2, in una directory Linux come $HOME/src, non sotto
+/mnt/c. Il percorso nativo scripts/install-tht.ps1 esiste per scenari PowerShell avanzati; per la
+prova riproducibile usare WSL2.
 
-```sh
-docker version
+### macOS
+
+- Docker Desktop installato, avviato e con alcuni GB liberi per immagini e modello di embedding.
+- Git, Bash, curl, OpenSSL e shasum.
+- Sono supportati Mac Intel e Apple Silicon se Docker Desktop supporta l’architettura restituita
+  dal Docker server.
+- Non installare Node.js, Python o Pi sull’host per questa procedura.
+
+### Linux, incluso Omarchy
+
+- Git, Bash, curl, OpenSSL e shasum.
+- Docker Engine e il plugin Docker Compose v2. Su Omarchy verificare prima:
+
+~~~
+command -v docker
 docker compose version
+docker info
+~~~
+
+Se Docker manca, installare Docker e Compose con il gestore pacchetti/procedura approvata dalla
+distribuzione, poi avviare il servizio. Su una distribuzione Arch-like il percorso tipico è:
+
+~~~
+sudo pacman -S docker docker-compose
+sudo systemctl enable --now docker
+sudo usermod -aG docker "$USER"
+~~~
+
+Dopo l’aggiunta al gruppo aprire una nuova sessione e ripetere docker info. Non installare Node.js,
+Python o Pi sull’host: sono dentro le immagini Docker.
+
+Su tutti i sistemi il controllo finale è:
+
+~~~
+bash scripts/check-standalone-prerequisites.sh
 docker version --format '{{.Server.Arch}}'
-```
+~~~
 
-L’ultima istruzione deve restituire `amd64`, `x86_64`, `arm64` o `aarch64`.
+L’architettura deve essere amd64, x86_64, arm64 o aarch64. Servono inoltre accesso al repository
+Gitea dell’applicazione, URL/branch e credenziali del repository workspace, raggiungibilità dal
+container degli endpoint DWH/LLM e le credenziali, token o certificati associati ai database.
 
-## 1. Clonare una revisione del progetto
+## 1. Cosa clonare
 
-Usare il repository di progetto su Gitea:
+Clonare solo l’applicazione:
 
-```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:
+Annotare la revisione. Il repository workspace verrà scaricato da tht setup --complete dentro un
+volume Docker persistente, usando URL, branch e trasporto indicati durante il setup.
 
-```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
+## 2. Installare il comando terminale
 
 Dal root del clone:
 
-```sh
+~~~
 bash scripts/check-standalone-prerequisites.sh
-export PATH="$HOME/.local/bin:$PATH"
+mkdir -p "$HOME/.local/bin"
 THT_INSTALL_DIRECTORY="$HOME/.local/bin" bash scripts/install-tht.sh
+export PATH="$HOME/.local/bin:$PATH"
 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.
+Il comando tht è l’unico componente nativo da installare. Costruisce il binario con Docker e
+orchestra Compose; non è un secondo runtime dell’applicazione.
 
-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. Preparare pochi segreti e avviare il setup completo
 
-## 3. Configurare e avviare l’installazione locale
+La prima esecuzione crea i placeholder protetti sotto deploy/local/secrets/ e si ferma se manca
+una credenziale necessaria. Compilare i file indicati e rilanciare lo stesso comando: i file di
+configurazione già compatibili vengono riutilizzati.
 
-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:
+~~~
+tht setup --complete --profile local --shell-mode full --shell-default-locale en
+~~~
 
-```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"
-```
+Durante il setup servono solo le informazioni operative che il computer non può conoscere:
 
-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 |
+| Richiesta | Cosa inserire |
 | --- | --- |
-| 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 |
+| Repository workspace | URL del repository dati/configurazione, non ThothII.git |
+| Branch | normalmente main |
+| Accesso | ssh con chiave e known_hosts, oppure https con credential file e CA |
+| DWH/LLM URL | endpoint senza token nella URL |
+| Login locale | utente e password iniziale richiesti dal prompt |
 
-La configurazione generata è locale e ignorata da Git:
+Il setup crea automaticamente le password casuali del Catalog e le scrive in operator.env come
+percorsi, non come valori. Esegue docker compose config, costruisce le immagini, avvia il Catalog,
+esegue catalog-migrate, avvia lo stack e importa il repository workspace. L’import attiva anche
+l’Evidence dichiarata: almeno i file source presenti nel workspace vengono materializzati nel
+registro locale.
 
-```text
-deploy/local/thothii-installation.yaml
-deploy/local/operator.env
-deploy/local/auth/
-deploy/local/secrets/
-```
+### Il file da compilare
 
-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.
+Il file principale è:
 
-### Completare i file protetti
+~~~
+deploy/local/secrets/thothii.secrets
+~~~
 
-Se il setup ha creato template vuoti, inserire i valori con un editor locale:
+Inserire solo righe NOME=VALORE necessarie al modelCatalog e agli adapter, per esempio una API key
+LLM (DEEPSEEK_API_KEY, OPENAI_API_KEY o quella dichiarata dal catalogo) ed eventualmente
+THT_DWH_API_KEY. I nomi ammessi sono documentati in deploy/secrets/README.md. Non mettere token
+nelle URL, nel repository o nei comandi.
 
-```sh
-chmod 600 deploy/local/secrets/*
-"${EDITOR:-vi}" deploy/local/secrets/thothii.secrets
-```
+Due precisazioni evitano gli errori più comuni:
 
-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.
+- se il catalogo usa pi_auth, il token LLM va nel file Pi pi-auth.json creato dal setup; {} è solo
+  un placeholder e non abilita alcun modello;
+- le credenziali specifiche di un database workspace (password PostgreSQL, API token REST, chiave
+  SSH del tunnel, known_hosts, CA) non vanno nel repository workspace: si inseriscono per workspace
+  in Database Management, che le conserva nel Catalog cifrato. Il workspace indica database/schema
+  e trasporto; l’installatore deve ottenere dal proprietario il valore corretto.
 
-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.
+Per un repository workspace privato sono inoltre indispensabili i file Git richiesti dal trasporto:
+una chiave SSH e known_hosts, oppure credential file HTTPS e CA. Sono file di trasporto, non un
+secondo bundle da committare. Per ridurre i file da compilare, usare SSH con una deploy key già
+autorizzata.
 
-Prima dell'avvio completare anche questi passaggi:
+## 4. Controlli automatici e test da terminale
 
-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.
+Il setup verifica file, permessi, descriptor, Compose, Docker, autenticazione, servizi, Pi e
+workspace. Dopo l’avvio usare questi comandi in qualunque momento:
 
-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.
+~~~
+INSTALLATION="$PWD/deploy/local/thothii-installation.yaml"
+tht --installation "$INSTALLATION" doctor --json
+tht --installation "$INSTALLATION" workspace pull --json
+tht --installation "$INSTALLATION" workspace test --json
+~~~
 
-```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
-```
+workspace test prova, per ogni workspace attivo, il binding del database e le credenziali, Evidence,
+Qdrant e il servizio embedding. Restituisce exit code diverso da zero se manca il binding del
+database o una connessione non è utilizzabile. Prima di eseguirlo l’installatore deve aver
+configurato il database in Database Management: il workspace repository da solo non può contenere
+la password.
 
-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.
+Per una verifica generale del core, doctor --json è il test ripetibile e non distruttivo. Il test
+funzionale finale deve inoltre aprire http://127.0.0.1:8080, autenticarsi e completare una domanda
+reale fino alla SQL finale.
 
-## 4. Verificare l’installazione
+## Attività che può svolgere solo l’installatore
 
-Il descriptor generato per l’ID predefinito è:
+La procedura automatizza il bootstrap, non può inventare decisioni o autorizzazioni aziendali.
+L’installatore deve completare e registrare:
 
-```sh
-INSTALLATION="$(pwd -P)/deploy/local/thothii-installation.yaml"
-test -f "$INSTALLATION"
-bash scripts/verify-standalone-install.sh "$INSTALLATION"
-```
+1. quali LLM sono utilizzabili, il relativo modelCatalog e le API key collegate; poi eseguire
+   tht pi test e tht doctor;
+2. per ogni database: configurazione, test connessione, sincronizzazione dello schema e
+   generazione delle descrizioni;
+3. consolidamento umano delle descrizioni generate;
+4. generazione delle entry semantiche in Qdrant tramite workspace preprocess run;
+5. generazione delle FK suggerite dal naming, come complemento alle FK lette dallo schema, revisione
+   umana delle proposte e caricamento delle relazioni approvate in Qdrant;
+6. verifica periodica con tht doctor --json e tht workspace test --json;
+7. una domanda reale completata con successo, senza errori di connessione o modello.
 
-Il verificatore è read-only: esegue `tht doctor --json` e `tht status`, senza ristartare lo stack,
-rigenerare la configurazione o stampare il contenuto dei segreti.
+La configurazione è dichiarata completa solo quando tutti i punti applicabili sono stati eseguiti,
+le decisioni sono state registrate e i due test terminali sono verdi. Il core è dichiarato usabile
+solo dopo la domanda reale, non perché il frontend risponde a /health.
 
-### Gate A — smoke di piattaforma, su tutti e tre i computer
+## Gate A e Gate B
 
-Registrare per ogni macchina:
+### Gate A — piattaforma
 
-```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:
+### Gate B — usabilità
 
-```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
-```
+tht --installation "$INSTALLATION" workspace test --json
+curl --fail --silent --show-error http://127.0.0.1:8080/health
+~~~
 
-`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.
+Poi eseguire una domanda reale e fermare/riavviare con tht stop e tht start. Non usare docker
+compose down --volumes: cancella Catalog, sessioni, Qdrant e il modello embedding.
 
 ## Diagnosi rapida
 
-| Sintomo | Controllo |
+| Sintomo | Azione |
 | --- | --- |
-| `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.
+| Docker Engine is not reachable | avviare Docker Desktop o systemctl e ripetere docker info |
+| Omarchy non trova docker | installare Docker/Compose, abilitare il servizio e riaprire la sessione |
+| Windows vede Docker ma Bash fallisce | usare Ubuntu WSL2 e abilitarne l’integrazione in Docker Desktop |
+| pull workspace fallisce | controllare URL, branch, chiave/credential file e known_hosts dal container |
+| workspace test segnala binding mancante | configurare database, token/password e CA in Database Management |
+| Pi non è pronto | compilare pi-auth.json o la chiave dichiarata dal modelCatalog, poi eseguire tht pi test |
 
 ## Documenti collegati
 
-- [Install and first start](first-start.md)
-- [Shell and localization](shell-and-language.md)
-- [Workspace operations](../operations/workspaces.md)
-- `deploy/secrets/README.md` (runtime secrets)
+- [Installazione e primo avvio](first-start.md)
+- [Operazioni sui workspace](../operations/workspaces.md)
+- [Database Management](../operations/database-management.md)
+- [Configurazione dei modelli](../general/pi-configuration.md)
+- deploy/secrets/README.md
+
+La pubblicazione di immagini su Docker Hub e gli installer nativi DMG/MSI/AppImage restano attività
+successive: questa procedura parte dal clone Gitea e non richiede immagini Docker Hub pre-pubblicate.

docs/operations/shell-and-localization.md

@@ -54,7 +54,7 @@ Omics. Le preferenze non modificano il descrittore installato.
 Per una nuova installazione autonoma, selezionare esplicitamente full:
 
 ```bash
-tht setup --profile local --shell-mode full --shell-default-locale en
+tht setup --complete --profile local --shell-mode full --shell-default-locale en
 ```
 
 Il setup senza opzioni shell conserva per compatibilità il default embedded.

docs/plans/2026-09-27-benchmark-examples.md

@@ -0,0 +1,175 @@
+# Tre esempi locali per l'installazione guidata
+
+Stato: nota esplorativa conservata; requisiti definiti nel PRD e implementazione
+rinviata su richiesta dell'utente.
+Requisiti correnti e decisioni aperte sono ora raccolti nel
+[PRD dei database di esempio](2026-09-27-example-databases-prd.md), che prevale
+su questa nota esplorativa in caso di divergenza.
+Branch: `codex/benchmark-examples`, derivato da `codex/guided-standalone-install`
+al commit `67ee5262`. Collegamento al progetto installazione:
+`docs/plans/2026-09-27-guided-installation-resumption.md` sul branch di origine.
+
+## Requisiti dell'utente
+
+- Tre database pubblicamente scaricabili da BIRD o altro benchmark, con evidence.
+- Tre livelli di complessità crescente; preferenza per dati in CSV.
+- Esempi da implementare in locale.
+- Caricamento opzionale tramite CLI dal repository dei workspace: selezione di
+  uno, due o tutti e tre i database, dopo il setup; integrazione nel setup da valutare.
+- Dati, schema PostgreSQL commentato ed Evidence disponibili per ogni esempio.
+- Domande in un documento di accompagnamento per esercitarsi, senza SQL target.
+- Collaudo in tre tappe: Windows, Linux Omarchy, macOS.
+
+### Criterio chiarito dall'utente
+
+ThothII viene usato con human in the loop: questo progetto non serve a misurarlo
+contro un benchmark. I benchmark sono soltanto fonti di database e documentazione.
+Numero di domande, gold SQL, percentuali di correttezza e copertura delle annotazioni
+per domanda non sono criteri di selezione o di accettazione.
+Le domande sono invece utili come materiale didattico: il prodotto le include in
+un documento separato dalle Evidence, senza soluzioni SQL o valutazione automatica.
+
+Si cercano complessità relazionale e semantica e documentazione sostanziale da
+curare come Source Evidence: significati, regole aziendali, formule, codifiche,
+granularità e relazioni. Documenti non collegati ai quesiti del benchmark contano
+quanto quelli collegati. DDL, righe di esempio e numero di file da soli non
+dimostrano una buona documentazione di dominio. Dopo il confronto delle alternative,
+il trio per cui l'utente richiede ora la procedura è Financial, European Football e F1.
+
+## Dataset proposti
+
+California Schools è escluso per richiesta dell'utente. European Football è richiesto;
+l'utente ha inoltre chiesto di valutare Spider 2.0 e la disponibilità di evidence.
+La proposta corrente comprende Financial e European Football da BIRD e F1 da
+Spider 2.0-Lite. Shopify, QuickBooks e Workday restano alternative documentate.
+I livelli sono una progressione didattica proposta per ThothII.
+
+| Livello | Database | Motivo | Fonti per le Evidence |
+| --- | --- | --- | --- |
+| Primo percorso | BIRD `financial` | Conti, clienti, prestiti e movimenti | Codifiche di dominio e regole nelle annotazioni BIRD |
+| Intermedio | BIRD `european_football_2` | Campionati, squadre, giocatori e partite | Stagioni, significato degli indicatori e aggregazioni nelle annotazioni BIRD |
+| Avanzato | Spider 2.0-Lite `f1` | Stagioni, gare, piloti, giri, pit stop e cambi di posizione; 29 tabelle dichiarate | Documenti di dominio sui sorpassi e sui tipi di giro, da curare e integrare dove insufficienti |
+
+Revisione Hugging Face BIRD osservata:
+`f65faf4ae3b638c1fa6df1d3370c8d92c8366301`.
+
+Le evidence BIRD comprendono spiegazioni di codici, significati di colonne e regole di
+calcolo. Sono annotazioni legate alle domande; richiedono adattamento e revisione
+per diventare Source Evidence di ThothII. Non sono già un archivio ThothII pronto.
+
+Le definizioni dbt sono fonti da curare, non Evidence Unit già importate in ThothII.
+Non contare ogni descrizione di colonna come un'evidence distinta. I file tecnici
+delle librerie dbt non rientrano nel materiale semantico del database.
+Revisione Spider2 osservata: `cafb867313aab4e674652054198f383cf4018943`.
+
+Le ricerche motivate e le alternative sono in
+`docs/research/2026-09-27-spider2-lite-evidence-candidates.md` e
+`docs/research/2026-09-27-spider2-dbt-evidence-candidates.md`.
+
+## Fonti e formati
+
+- [Dataset ufficiale e licenza dichiarata CC BY-SA 4.0](https://huggingface.co/datasets/birdsql/bird_mini_dev).
+- [Domande PostgreSQL, evidence e SQL di riferimento](https://huggingface.co/datasets/birdsql/bird_mini_dev/blob/f65faf4ae3b638c1fa6df1d3370c8d92c8366301/data/mini_dev_pg-00000-of-00001.json).
+- [Istruzioni ufficiali e pacchetto database](https://github.com/bird-bench/mini_dev).
+- [Pacchetto completo indicato dalla dataset card](https://drive.google.com/file/d/13VLWIwpw5E3d5DUkMvzw7hvHE67a4XkG/view?usp=sharing).
+- [Archivio ZIP collegato dal repository ufficiale](https://bird-bench.oss-cn-beijing.aliyuncs.com/minidev.zip):
+  risposta HEAD 200, 800943648 byte al controllo; contenuto non ancora scaricato né
+  confrontato con il pacchetto aggiornato della dataset card.
+
+I CSV `database_description` descrivono schema e valori, non contengono le righe
+delle tabelle. I dati sono forniti come database SQLite e materiale per PostgreSQL/
+MySQL. Proposta: mantenere PostgreSQL come destinazione locale e, se utile, produrre
+CSV riproducibili insieme a DDL, tipi e vincoli. Non usare CSV senza schema come
+unica rappresentazione del database. Conservare provenienza, versione, attribuzione
+e licenza con gli artefatti derivati.
+
+Fonti Spider 2.0-Lite per F1:
+
+- [Istruzioni per scaricare i database SQLite locali](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/README.md).
+- [Schema e metadati F1](https://github.com/xlang-ai/Spider2/tree/main/spider2-lite/resource/databases/sqlite/f1).
+- [Classificazione dei sorpassi](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/f1_overtake.md).
+- [Tipi di giro](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/lap_type.md).
+
+I tre database sorgente sono SQLite. Esportazione CSV e caricamento PostgreSQL
+dovranno preservare tipi, relazioni, granularità e contenuto dei dati selezionati.
+I file sono stati individuati negli archivi; i dati completi non sono stati scaricati
+né convertiti durante la progettazione.
+
+## Proposta di download e caricamento PostgreSQL
+
+Questa sezione risponde alla richiesta di fattibilità e non autorizza né attesta
+un'implementazione già eseguita.
+
+### Destinazione
+
+Il Compose include `catalog-db`, PostgreSQL 17.6, con volume `catalog-data` e database
+`thothii_catalog`. Quest'ultimo ospita le informazioni applicative del Catalog e
+la persistenza Memory. Proposta per le installazioni dimostrative: riutilizzare lo
+stesso servizio PostgreSQL, creando tre database separati, con nomi da finalizzare:
+`example_financial`, `example_football`, `example_f1`. Ogni database avrà un solo
+schema applicativo, un workspace associato e un ruolo di interrogazione in sola
+lettura. L'importazione userà un ruolo distinto con permessi di scrittura.
+
+La creazione degli esempi deve essere una manutenzione esplicita rieseguibile, non
+un'aggiunta affidata unicamente agli script di inizializzazione del volume PostgreSQL.
+Le migrazioni Catalog e i suoi ruoli runtime rimangono separati dal caricatore.
+La condivisione del servizio implica condivisione di risorse, volume e gestione
+backup; non equivale a isolamento fra istanze PostgreSQL indipendenti.
+
+### Sequenza prevista
+
+1. Selezione esplicita di uno, due o tre esempi, anche dopo il primo setup.
+2. Manifest versionato per ciascun esempio: URL ufficiali, revisione/checksum,
+   file nell'archivio, fonti documentali, licenze e versione della conversione.
+   Cache dei pacchetti comuni per evitare download duplicati.
+3. Download ed estrazione dei SQLite e della documentazione. BIRD: descrizioni CSV
+   e annotazioni evidence, conservando il contesto necessario a interpretarle.
+   F1: metadati dello schema e documenti di dominio. Nessuna generazione automatica
+   di nuove regole presentate come se fossero evidence originali.
+4. Ispezione dello schema e dei dati effettivi; conversione SQLite verso DDL
+   PostgreSQL e CSV, con mapping espliciti per tipi, date, booleani, valori null,
+   identificatori e colonne prive di tipo. Rilevare PK/FK presenti e distinguere
+   relazioni documentate o proposte da quelle effettivamente vincolate nella sorgente.
+5. Caricamento in database di preparazione dedicati; creazione degli indici e
+   vincoli verificati, confronto delle righe e dei valori e controlli relazionali.
+   Un fallimento lascia l'esempio non pronto senza sostituire una versione funzionante.
+6. Pubblicazione dei database validati e registrazione dei binding nel Catalog;
+   creazione dei workspace e sincronizzazione degli schemi via servizi esistenti.
+7. Importazione separata: descrizioni nel Catalog; documenti e regole nelle Source
+   Evidence del workspace, con provenienza. Le Evidence restano artefatti del
+   modulo Evidence; la proiezione ricercabile appartiene a Qdrant.
+8. Revisione umana/consolidamento delle Evidence e delle relazioni proposte,
+   preprocessing e controlli di utilizzabilità. La disponibilità dei file scaricati
+   non equivale a un workspace pronto.
+
+Il processo conserva stato e versioni per riprendere dopo errori, evita duplicazioni
+e non sovrascrive Evidence curate o dati esistenti durante una normale riesecuzione.
+Download ed elaborazione devono usare componenti containerizzati, mantenendo il
+percorso Windows/WSL2 senza richiedere Python o Node aggiuntivi sull'host.
+
+## Decisione architetturale aperta
+
+Gli ADR 0001 e 0003 e il glossario corrente prevedono un database per workspace.
+La richiesta di un workspace con tre database richiede quindi una scelta esplicita.
+Proposta: un pacchetto/repository di esempi con tre workspace indipendenti, ognuno
+associato al proprio database. Nessuna modifica multi-database è approvata finora.
+
+## Lavoro previsto dopo la definizione
+
+1. Fissare versione e checksum dei dati, ispezionare schema, tipi, chiavi e
+   documentazione di dominio; definire percorsi dimostrativi di complessità crescente.
+2. Preparare il caricamento locale selettivo dei tre dataset, con dati e ruoli
+   distinti dal Catalog applicativo, ripresa e riesecuzione senza duplicazioni.
+3. Preparare descriptor e Source Evidence con provenienza per ogni esempio;
+   esplicitare ciò che è documentato e ciò che richiede una decisione del curatore.
+4. Registrare binding nel Catalog, sincronizzare schema e predisporre il percorso
+   di revisione/consolidamento e preprocessing dei workspace selezionati.
+5. Integrare nel setup la scelta opzionale dei dataset e mostrare per ciascuno
+   caricamento, configurazione, Evidence e stato di utilizzabilità.
+6. Verificare tutte le sette selezioni non vuote dei tre esempi, la riesecuzione e
+   gli errori di download/importazione. Collaudare una domanda reale per ciascun
+   esempio installato, poi arresto e riavvio, prima su Windows.
+
+La selezione opzionale comprende anche la possibilità di installare ThothII senza
+esempi. Nessun download massivo, caricamento database o implementazione del setup
+è stato eseguito durante questa proposta.

docs/plans/2026-09-27-example-databases-prd.md

@@ -0,0 +1,402 @@
+# PRD — Database di esempio per ThothII
+
+Data: 2026-09-27. Stato: requisiti D1–D8 approvati tramite `grill-with-docs`;
+implementazione rinviata su richiesta dell'utente; non iniziata.
+Branch di progettazione: `codex/benchmark-examples`.
+
+Il branch conserva la progettazione per una ripresa successiva. La definizione
+della procedura di installazione prosegue separatamente su
+`codex/guided-standalone-install`; non deve presumere che la CLI o i database di
+esempio descritti qui siano già disponibili.
+
+Questo PRD raccoglie i requisiti correnti e sostituisce, in caso di divergenza,
+le proposte nella [nota esplorativa](2026-09-27-benchmark-examples.md).
+Gli aspetti tecnici da verificare prima del rilascio sono distinti dalle decisioni
+di prodotto approvate e non attestano funzionalità già implementate.
+
+## Problema e risultato desiderato
+
+Chi installa ThothII deve poter scegliere e caricare uno, due o tre database di
+esempio, ottenendo dati reali, schema commentato, Evidence disponibili e un documento
+di domande per esercitarsi. Il percorso deve funzionare anche dopo l'installazione,
+senza obbligare a reinstallare ThothII o a conoscere la sua architettura interna.
+
+La distribuzione avviene dal repository dei workspace: oltre alle definizioni dei
+workspace, il repository ospita una cartella `examples/` con la CLI e quanto serve
+a scaricare e predisporre gli esempi su richiesta. Il normale aggiornamento del
+repository non deve eseguire importazioni.
+
+Il repository pubblico ThothII su `git.tylconsulting.it` deve rimandare al repository
+pubblico dedicato agli esempi, ospitato su Gitea e gestito da TYL Consulting.
+L'URL esatto di destinazione resta da definire; non si presume che debba coincidere
+con l'istanza Gitea del repository ThothII. README e documentazione di installazione
+devono rendere reperibili CLI, workspace e istruzioni dal repository principale.
+
+ThothII ha un processo human in the loop. Le domande sono spunti didattici, senza
+risposte SQL da riprodurre, punteggi, classifiche o confronto automatico col benchmark.
+
+## Requisiti confermati
+
+| ID | Requisito |
+| --- | --- |
+| R1 | Tre esempi: BIRD Financial, BIRD European Football, Spider 2.0-Lite F1. |
+| R2 | Selezione di uno, due o tutti e tre; gli esempi sono facoltativi. |
+| R3 | Caricare dati e schema PostgreSQL, inclusi commenti di tabelle e colonne. |
+| R4 | Accompagnare ogni esempio con le Evidence disponibili e la loro provenienza, curate prima del rilascio e indicizzate durante il caricamento. |
+| R5 | Fornire le domande disponibili in un documento leggibile per esercitarsi. |
+| R6 | Escludere gli SQL target dei benchmark dal prodotto distribuito agli utenti. |
+| R7 | Verificare esplicitamente la conversione dei tipi e dei valori verso PostgreSQL. |
+| R8 | Distribuire una CLI attraverso il repository dei workspace, nella cartella degli esempi. |
+| R9 | Consentire il caricamento tramite CLI autonoma dopo l'installazione e richiamare la stessa procedura come ultimo passo facoltativo del setup. |
+| R10 | Collaudare Windows, poi Omarchy, infine macOS, in tre passaggi separati. |
+| R11 | Distribuire pacchetti PostgreSQL già convertiti e verificati, con ricetta di conversione riproducibile. Valutare conversione locale solo per fonti non redistribuibili. |
+| R12 | Concludere con workspace subito utilizzabili: dati, commenti, Evidence curate, metadati sincronizzati e indicizzazione completata. |
+| R13 | La procedura deve prevedere una copia indipendente del repository degli esempi, senza memoria Git dell'originale, oppure uno scaricamento con accesso al repository pubblico in sola lettura. Workspace ed Evidence locali restano modificabili; nessuna credenziale o operazione di scrittura verso l'originale. |
+
+DDL, comandi di importazione e controlli tecnici SQL fanno parte del caricatore;
+R6 riguarda le soluzioni alle domande dei benchmark.
+
+## Perimetro dei tre esempi
+
+| Esempio | Percorso didattico | Materiale semantico disponibile |
+| --- | --- | --- |
+| Financial | Iniziale | Descrizioni BIRD, codifiche, annotazioni Evidence associate ai quesiti. |
+| European Football | Intermedio | Descrizioni BIRD, significato degli indicatori e annotazioni Evidence. |
+| F1 | Avanzato | Metadati Spider 2.0-Lite e documenti di dominio, fra cui sorpassi e tipi di giro. |
+
+Questa progressione è didattica, non una misura delle prestazioni di ThothII.
+La maggiore complessità di F1 non implica una copertura semantica completa:
+le lacune vanno dichiarate nel materiale di accompagnamento.
+
+Le fonti sono SQLite e documentazione separata. I CSV BIRD delle descrizioni non
+sono i dati delle tabelle. La dimensione PostgreSQL, inclusi indici e spazio
+temporaneo di caricamento, deve essere misurata durante la preparazione; non si
+deduce dalla sola dimensione SQLite. Le misure sorgente sono nella
+[ricerca sulle dimensioni](../research/2026-09-27-example-database-sizes.md).
+
+## Architettura di riferimento
+
+ThothII include già il servizio PostgreSQL `catalog-db`; il database applicativo
+è `thothii_catalog`. Il progetto propone di usare la stessa istanza per tre database
+di esempio distinti, senza mescolare le loro tabelle con quelle applicative.
+
+Il contratto corrente associa un database a un workspace: il pacchetto contiene
+quindi tre workspace, ciascuno con il proprio database e un singolo schema
+applicativo. Non è previsto un cambiamento verso workspace multi-database.
+
+La CLI di importazione usa credenziali di caricamento separate dalle credenziali
+in sola lettura con cui ThothII interroga gli esempi. Non riutilizza il ruolo runtime
+del Metadata Catalog per creare o caricare database. I segreti restano locali,
+fuori dal repository, dai manifest pubblici e dai log.
+
+Il PostgreSQL interno non richiede l'esposizione di una porta sull'host: il
+caricatore deve poter operare nella rete dello stack. Una connessione a un server
+PostgreSQL alternativo è un'eventuale estensione, non un requisito iniziale.
+
+## Distribuzione e contenuti
+
+Struttura illustrativa, da adattare alle convenzioni del repository prescelto:
+
+```text
+thoth-workspaces.yaml
+examples/
+  README.md
+  cli/
+  manifests/
+    financial.yaml
+    european-football.yaml
+    f1.yaml
+  docs/
+    financial-practice.md
+    european-football-practice.md
+    f1-practice.md
+example-financial/
+  workspace.yaml
+  evidence/
+    source/
+    curated/
+example-football/...
+example-f1/...
+```
+
+La Source Evidence rimane nel percorso canonico `<workspace-id>/evidence`;
+il documento di esercitazione è esterno al corpus delle Evidence. Il solo fatto
+di trovarsi nel repository non deve rendere le domande regole di dominio ricercabili.
+
+**Adeguamento necessario in ThothII:** il lettore attuale considera workspace tutte
+le directory alla radice, eccetto `workspace-docs`, e ne verifica la corrispondenza
+con il catalogo. Una nuova `examples/` non è quindi accettata automaticamente.
+Il sottoprogetto deve estendere esplicitamente questo contratto per riconoscerla
+come directory ausiliaria, preservando la validazione dei veri workspace;
+non deve registrarla come workspace fittizio. Riferimenti:
+`backend/src/workspaces/git-repository.ts:212` e
+`backend/src/workspaces/registry.ts:515`.
+
+Nel repository Git risiedono CLI, manifest, documentazione e definizioni dei
+workspace. Gli archivi voluminosi dei dati sono scaricati su richiesta da URL
+versionati, con checksum, cache e attribuzioni. Il luogo di pubblicazione dei
+pacchetti derivati dipende dalla decisione sulla modalità di conversione e dai
+diritti di redistribuzione delle singole fonti: la licenza del codice di un
+benchmark non prova da sola la licenza di tutti i dati inclusi.
+
+Ogni manifest identifica almeno: esempio e workspace, versione del pacchetto,
+revisioni e URL delle fonti, file da estrarre, checksum, licenze/attribuzioni,
+versione della conversione, compatibilità PostgreSQL/ThothII, inventario degli
+artefatti e risultati attesi dei controlli. Versioni e nomi non sono ricavati
+silenziosamente da un riferimento mobile come `main`.
+
+La verifica delle fonti del 2026-09-27 ha rilevato CC BY-SA 4.0 nella dataset card
+BIRD e MIT per software/documentazione nel repository Spider2. Questo non chiarisce
+da solo la redistribuibilità di ciascun database fornito negli archivi esterni:
+per i tre dump PostgreSQL lo stato è ancora da verificare, non un divieto accertato.
+Registrare licenza dichiarata, fonte e stato della verifica separatamente per dati,
+descrizioni, Evidence, domande e codice. La verifica sulla versione esatta è una
+condizione di pubblicazione dei pacchetti; la conversione locale rimane l'eccezione
+prevista da D2. Fonti: [card BIRD](https://huggingface.co/datasets/birdsql/bird_mini_dev),
+[repository BIRD](https://github.com/bird-bench/mini_dev),
+[licenza Spider2](https://github.com/xlang-ai/Spider2/blob/main/LICENSE) e
+[download Spider2-Lite](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/README.md).
+
+## Schema commentato e conversione
+
+Per ogni database si prepara un contratto di conversione per tabella e colonna,
+fondato sull'ispezione sia dello schema sia dei valori effettivi. Non basta
+tradurre il tipo dichiarato da SQLite, che può contenere valori eterogenei.
+
+| Area | Regola di accettazione |
+| --- | --- |
+| Interi e identificatori | Range compatibili, nessun overflow; i codici con zeri iniziali restano codici. |
+| Decimali e floating point | Precisione e scala dichiarate; nessun arrotondamento silenzioso. |
+| Date e orari | Formato, granularità e timezone documentati; non inventare una timezone. |
+| Durate | Non confonderle con orari del giorno; rappresentazione e unità esplicite. |
+| Booleani e categorie | Conversione solo con codifiche verificate; distinguere sconosciuto e falso. |
+| Null e testo | Distinguere NULL, stringa vuota e sentinelle; preservare Unicode, virgole e newline. |
+| Colonne senza tipo o miste | Profilazione completa e decisione esplicita; errore comprensibile se non conformi. |
+| Identificatori SQL | Mapping stabile e quoting coerente per maiuscole, parole riservate e caratteri speciali. |
+| PK, FK e indici | Separare vincoli presenti, relazioni documentate e relazioni inferite; verificare prima di imporre. |
+| Contenuti strutturati | Conservare il significato di XML/JSON/testi complessi senza trasformazioni non documentate. |
+
+Ogni cambiamento rispetto alla sorgente compare in un rapporto di conversione.
+Per casi anomali non sono ammessi scarto di righe o sostituzione con NULL senza
+una regola esplicita e verificata. I controlli confrontano conteggi e valori
+normalizzati per tabella; un solo confronto dei conteggi non basta.
+
+Le descrizioni disponibili diventano veri `COMMENT ON TABLE` e
+`COMMENT ON COLUMN` nel database PostgreSQL, mantenendo provenienza e segnalando
+le descrizioni mancanti. Eventuali integrazioni redazionali sono distinte dalle
+descrizioni originali. Questi commenti devono essere visibili anche nel Metadata
+Catalog usato da ThothII; la sola presenza dei commenti in PostgreSQL non soddisfa
+il requisito se la sincronizzazione del Catalog li ignora.
+
+Il percorso esiste già: `backend/src/catalog/schema-introspector.ts:84` e `:106`
+leggono `pg_description`; `metadata-snapshot.ts:52` applica la precedenza
+descrizione curata, descrizione generata, commento sorgente. Il collaudo deve
+considerare questa precedenza: non cancellare una descrizione curata per far
+apparire un commento importato.
+
+## Evidence e documento di esercitazione
+
+Le fonti documentali e le annotazioni Evidence sono raccolte senza introdurre
+regole inventate. Un'annotazione specifica di una domanda conserva il contesto
+necessario: non diventa automaticamente una regola valida per tutto il database.
+Duplicati e conflitti vengono riconciliati conservando i riferimenti originali.
+
+L'archivio distingue Source Evidence e Curated Evidence nel formato supportato
+da ThothII. La curation avviene prima del rilascio: il pacchetto contiene le fonti
+e le unità curate, con riferimenti verificabili e lacune dichiarate. I file originali
+non vengono presentati come Evidence già revisionate. Qdrant contiene la proiezione
+ricercabile, non sostituisce l'archivio delle Evidence. L'utente finale può modificare
+e arricchire la curation, ma non deve completarla per iniziare a usare l'esempio.
+
+Il documento di esercitazione contiene domande disponibili, fonte e identificativo,
+raggruppamento tematico, eventuali note sui limiti dei dati e riferimenti utili.
+Non contiene soluzioni SQL né risposte attese per il confronto automatico.
+Se necessario, si adattano i riferimenti ai nomi PostgreSQL, rendendo riconoscibile
+la modifica. Guide, domande e contenuti semantici curati sono disponibili in italiano
+e inglese, conservando gli originali e rendendo riconoscibili le traduzioni;
+gli identificatori SQL restano invariati. Le rappresentazioni linguistiche di una
+stessa Evidence non devono duplicarne il risultato nella ricerca.
+
+Gli archivi originali possono includere SQL target. L'estrazione per il prodotto
+ammette solo i campi necessari a schema, documentazione, Evidence e domande;
+gli SQL target non entrano nei workspace, negli indici o nei documenti didattici.
+
+## Comportamento della CLI
+
+L'interfaccia esatta sarà definita dopo le decisioni di questo PRD. Le capacità
+richieste sono: elencare gli esempi e i prerequisiti, scegliere un sottoinsieme,
+scaricare/verificare, caricare, collegare i workspace e mostrare lo stato per esempio.
+
+1. Individuare l'installazione e verificare compatibilità, servizi e spazio.
+2. Risolvere i manifest e mostrare cosa verrà caricato per gli esempi scelti.
+3. Scaricare solo i pacchetti necessari; riutilizzare gli archivi condivisi in cache.
+4. Verificare ed estrarre il pacchetto PostgreSQL già convertito; l'eventuale
+   conversione locale eccezionale deve essere dichiarata dal manifest.
+5. Caricare in un database di preparazione e verificarne dati, tipi, vincoli e commenti.
+6. Rendere disponibile il database verificato e registrare il binding nel Catalog.
+7. Sincronizzare metadati, importare le Evidence già curate ed eseguire
+   consolidamento/preprocessing per rendere il workspace subito utilizzabile.
+8. Fornire un riepilogo per esempio, il documento con le domande e il prossimo passo.
+
+Lo stato deve distinguere almeno dati caricati, metadati sincronizzati, Evidence
+disponibili, indicizzazione completata e workspace pronto. Un download concluso
+non equivale a un esempio utilizzabile. Se gli esempi hanno esiti diversi, il
+riepilogo deve mostrare successi e fallimenti separatamente.
+
+La riesecuzione della stessa versione non duplica dati e non sovrascrive le
+Evidence modificate dall'utente. Un errore non sostituisce un database funzionante;
+lo stato permette di riprendere dalle fasi completate. Il preprocessing corrente
+non è internamente resumable: in caso di errore quella fase viene rieseguita.
+Aggiornamento di versione, ripristino e rimozione distruttiva richiedono operazioni
+esplicite distinte dalla normale installazione e sono esclusi dalla prima versione
+della CLI, che comprende elenco/selezione, installazione, verifica e ripresa dopo errore.
+
+L'integrazione deve usare le API esistenti per creazione del database nel Catalog,
+binding e secret store (`backend/src/routes/catalog-databases.ts`), con
+autenticazione e permessi appropriati. La sincronizzazione dello schema è un
+run distinto, con conferma esplicita (`backend/src/routes/catalog-schema.ts:189`
+e `:223`): il progetto deve definire come presentare o gestire quella conferma
+senza aggirarne il contratto. `workspace preprocess run` ed Evidence consolidate
+sono già disponibili come CLI, ma non creano binding o credenziali per conto del
+caricatore. Si veda [il contratto preprocessing](../contracts/workspace-preprocessing-cli.md).
+
+## Collaudo e condizioni di completamento
+
+- Ogni esempio ha un inventario verificato di schema, dati, commenti, Evidence e domande.
+- Il repository con `examples/` supera la validazione e mantiene i controlli
+  sulle directory dei workspace; nessun file della CLI viene eseguito dal pull.
+- Tutte le sette selezioni non vuote producono esclusivamente gli esempi scelti.
+- La selezione di nessun esempio non ostacola l'installazione di ThothII.
+- Si verificano conversione dei valori, vincoli, commenti e propagazione al Catalog.
+- Il ruolo di interrogazione può leggere i dati e non può modificarli.
+- Interruzione del download, checksum errato, errore d'importazione e spazio
+  insufficiente producono uno stato recuperabile e non danneggiano esempi esistenti.
+- Ripetere un'installazione completata non altera dati né curation locale.
+- La copia indipendente non contiene storia Git o relazione di fork dell'originale,
+  né remote verso di esso; mantiene versione, checksum, licenze e attribuzioni.
+- Il percorso di download non richiede credenziali di scrittura verso il repository
+  pubblico e non esegue push. In entrambe le modalità l'utente può modificare
+  workspace ed Evidence locali e continuare a usarli dopo il riavvio.
+- Una sessione reale può interrogare ciascun esempio, con Evidence reperibili;
+  non è richiesto riprodurre l'SQL di un benchmark.
+- Ogni workspace risulta subito utilizzabile anche dopo riavvio; le Evidence
+  curate sono effettivamente reperibili e non solo presenti sul filesystem.
+- Primo rilascio verificato su Windows/WSL2 e Docker Desktop; secondo su Omarchy;
+  terzo su macOS. Nessuna dichiarazione di supporto a una tappa non ancora verificata.
+
+La proposta è eseguire conversione/caricamento in container, senza introdurre
+Python o Node obbligatori sull'host dell'utente. Il metodo di avvio/download della
+CLI resta da precisare in base alla scelta dei pacchetti.
+
+## Decisioni approvate con grill-with-docs
+
+Approvazione dell'utente del 2026-09-27: «ok a tutto», riferita a D1, D2 e D3.
+Nel round successivo l'utente approva D4 con precisazione della distribuzione Gitea,
+D5 e D7. Dopo il chiarimento approva anche D6, ribadendo che chi installa deve
+trovare tutto pronto, e aggiunge D8 sulla copia autonoma o sul download in sola lettura.
+
+| ID | Decisione | Esito approvato |
+| --- | --- | --- |
+| D1 | Quando proporre il caricamento? | CLI autonoma dopo il setup, richiamabile anche come ultimo passo facoltativo dello stesso setup. |
+| D2 | Dove convertire le sorgenti verso PostgreSQL? | Preparare e verificare pacchetti PostgreSQL versionati nella fase di rilascio; la CLI dell'utente scarica e carica. Conservare la ricetta di conversione riproducibile. Se una fonte non è redistribuibile, valutarne la conversione locale. |
+| D3 | Quanto deve essere pronto l'esempio dopo il caricamento? | Dati, commenti e Evidence curate in anticipo, già sincronizzate e indicizzate, per consentire subito una sessione; curation successiva resta disponibile all'utente. |
+| D4 | Repository di distribuzione | Il repository pubblico ThothII su git.tylconsulting.it rimanda a un repository pubblico dedicato agli esempi su Gitea gestito da TYL Consulting. Per installazioni con un repository proprio, il curatore integra i contenuti degli esempi in quel repository. Nessun nuovo supporto multi-repository in questo sottoprogetto. |
+| D5 | Lingua dei contenuti | Guide, domande e contenuti semantici curati in italiano e inglese; originali conservati, traduzioni riconoscibili e identificatori SQL invariati. Nessuna duplicazione della stessa Evidence nella ricerca. |
+| D6 | Preparazione e verifica delle Evidence | Il progetto prepara e controlla i contenuti; all'utente vengono sottoposte solo ambiguità o conflitti non risolvibili dalle fonti, con una proposta concreta. Chi installa riceve tutto pronto e non deve revisionare le Evidence per iniziare. |
+| D7 | Prima versione della CLI | Elenco/selezione, installazione, verifica e ripresa dopo errore. Aggiornamento di versione, reset e disinstallazione rimandati; nessuna sostituzione automatica di esempi modificati. |
+| D8 | Copia autonoma e sola lettura | Copia indipendente senza storia/remote/relazione di fork dell'originale, oppure scaricamento dal repository pubblico in sola lettura. Il limite riguarda la scrittura sul repository originale: workspace ed Evidence locali rimangono modificabili. Versioni, licenze e attribuzioni sono conservate. |
+
+La risposta «1» dell'utente conferma per D8 la sola lettura remota e la modificabilità locale.
+Nome e URL del repository destinazione saranno definiti prima della pubblicazione.
+Interfaccia CLI, autenticazione e custodia dei segreti saranno definite nella
+specifica tecnica coerentemente con i contratti esistenti. Le verifiche tecniche
+e dei diritti sulle fonti sono lavoro del progetto e non domande demandate all'utente.
+
+## Contesto del secondo round e chiarimento D6
+
+La verifica locale ha individuato il repository PSD privato, mentre i template
+generici riportano un URL esemplificativo. Non è stato individuato un repository
+concreto già destinato agli esempi. L'installazione supporta una sola sorgente Git:
+la scelta di un repository per gli esempi non deve sostituire implicitamente il
+repository già configurato in un'installazione esistente.
+
+D6 riguarda la verifica del significato delle Evidence adattate dalle fonti:
+per esempio, un'annotazione riferita a una singola domanda non può diventare una
+regola generale senza supporto documentale. Non riguarda la scrittura da zero delle
+Evidence da parte dell'utente o una revisione a ogni installazione.
+
+Chiarimento approvato per D6: il progetto prepara i contenuti, ne
+controlla provenienza, coerenza e adattamento a PostgreSQL; all'utente vengono
+sottoposte solo ambiguità o conflitti non risolvibili dalle fonti, con una proposta
+concreta. I punti irrisolti restano segnalati ed esclusi dalle regole pubblicate
+come verificate. L'utilizzatore finale riceve il materiale già curato.
+
+## D8 — Copia del repository e permessi
+
+Richiesta dell'utente: «fork del repository senza memoria dell'originale, o lo
+scarico in locale ma senza diritti di scrittura». Il risultato deve restare pronto
+all'uso e non richiedere un lavoro di curation a chi installa.
+
+La proposta tecnica per la copia indipendente è estrarre un rilascio verificato
+senza la directory `.git` originaria; se il runtime richiede Git, inizializzare
+una nuova storia locale, senza remote verso l'originale né associazione di fork
+sulla piattaforma. Un fork ordinario che conserva storia e relazione col repository
+originario non soddisfa questo significato di indipendenza. L'eventuale pubblicazione
+in un repository personale è un'operazione separata, non implicita nell'installazione.
+
+Versione del pacchetto, checksum, licenze e attribuzioni rimangono nel manifest e
+nella documentazione: l'assenza di memoria Git non elimina la provenienza dei dati
+e delle Evidence. Nessun aggiornamento automatico deve sovrascrivere una copia
+personalizzata.
+
+Per il percorso di download, la scelta approvata è accesso anonimo in sola
+lettura al repository pubblico, senza credenziali di scrittura e senza operazioni
+di push. File e archivio locale delle Evidence restano modificabili dall'utente.
+Il filesystem locale non è reso globalmente in sola lettura.
+
+**Adeguamento necessario nel runtime:** la copia senza `.git` non è oggi una sorgente
+completa per ThothII. Il lettore richiede `HEAD` e file committati
+(`backend/src/workspaces/git-repository.ts:198`); il refresh esegue fetch del branch
+da `origin` e rifiuta checkout sporchi o divergenze (`:467–485`). Il solo `git init`
+senza remote non completa quindi il percorso corrente.
+
+La specifica deve prevedere una sorgente locale autonoma, oppure una nuova copia
+Git locale usata come sorgente del checkout gestito: eventuali riferimenti Git
+interni all'installazione non devono puntare al repository pubblico originale.
+Il backend già accetta percorsi Git locali assoluti/file URL (`:60–64`), ma setup,
+configurazione e aggiornamento devono supportare coerentemente il percorso scelto.
+Le due modalità devono funzionare senza chiedere all'utente di configurare Git.
+
+Il download HTTPS anonimo è compatibile con il consumo remoto del backend; va
+verificato anche nel bootstrap dell'installazione. Il checkout gestito non è la
+cartella da sporcare con modifiche manuali: la procedura deve rendere esplicita una
+copia locale modificabile dei workspace e gestirne l'attivazione senza push verso
+l'originale. L'archivio locale delle Evidence è già separato e modificabile.
+Riferimenti: `docs/contracts/workspace-evidence-v3.md:218` e il contratto delle
+Evidence curate. I controlli di integrità del checkout non vanno disabilitati per
+ottenere la modificabilità richiesta.
+
+## Passaggio alla specifica tecnica
+
+La definizione dei requisiti è conclusa con D1–D8. La specifica dovrà tradurli in
+questi blocchi verificabili, prima dell'implementazione:
+
+1. Contratto del repository: cartella `examples/`, distribuzione pubblica e copia
+   autonoma o accesso remoto in sola lettura, con personalizzazioni locali persistenti.
+2. Preparazione dei tre pacchetti: fonti e diritti verificati, conversione di
+   schema/dati/tipi, commenti, Evidence curate e materiale didattico bilingue.
+3. CLI: download, verifica, importazione isolata, binding, sincronizzazione e
+   indicizzazione, stato e ripresa dopo errore, senza push verso l'originale.
+4. Integrazione facoltativa nel setup, collegamenti fra repository e documentazione.
+5. Collaudo Windows, successivamente Omarchy, infine macOS.
+
+## Riferimenti
+
+- [BIRD mini-dev: dati e documentazione](https://github.com/bird-bench/mini_dev).
+- [Dataset card BIRD](https://huggingface.co/datasets/birdsql/bird_mini_dev).
+- [Spider 2.0-Lite: download e formati](https://github.com/xlang-ai/Spider2/tree/main/spider2-lite).
+- [Ricerca sui candidati e sulle Evidence](../research/2026-09-27-spider2-lite-evidence-candidates.md).
+- [Contratto workspace/Evidence](../contracts/workspace-evidence-v3.md),
+  [modulo Evidence](../evidence.md), [glossario](../../CONTEXT.md),
+  [ADR 0001 — Metadata Catalog](../adr/0001-postgres-metadata-catalog.md),
+  [ADR 0003 — binding locali](../adr/0003-installation-local-database-bindings.md).

docs/research/2026-09-27-example-database-sizes.md

@@ -0,0 +1,49 @@
+# Dimensioni dei sei database candidati
+
+Verifica del 27 settembre 2026 tramite lettura HTTP Range della directory centrale
+degli archivi ZIP ufficiali. I valori sono le dimensioni non compresse dichiarate
+per i singoli file, non il consumo misurato dopo importazione in PostgreSQL.
+GB e MB sono decimali: 1 GB = 1.000.000.000 byte.
+
+| Database | Formato | Byte | GB | MB |
+| --- | --- | ---: | ---: | ---: |
+| Financial, BIRD Mini-Dev | SQLite | 71.294.976 | 0,071295 | 71,295 |
+| European Football, BIRD Mini-Dev | SQLite | 597.754.880 | 0,597755 | 597,755 |
+| F1, Spider 2.0-Lite | SQLite | 74.940.416 | 0,074940 | 74,940 |
+| Shopify, Spider 2.0-DBT, shopify001 | DuckDB iniziale | 19.935.232 | 0,019935 | 19,935 |
+| QuickBooks, Spider 2.0-DBT, quickbooks001 | DuckDB iniziale | 50.606.080 | 0,050606 | 50,606 |
+| Workday, Spider 2.0-DBT, workday001 | DuckDB iniziale | 28.323.840 | 0,028324 | 28,324 |
+| Totale | | 842.855.424 | 0,842855 | 842,855 |
+
+## Provenienza
+
+- [BIRD Mini-Dev ZIP](https://bird-bench.oss-cn-beijing.aliyuncs.com/minidev.zip),
+  collegato dal [repository ufficiale](https://github.com/bird-bench/mini_dev).
+  Archivio: 800.943.648 byte; Last-Modified 20 giugno 2024.
+  Entry: `minidev/MINIDEV/dev_databases/financial/financial.sqlite` e
+  `minidev/MINIDEV/dev_databases/european_football_2/european_football_2.sqlite`.
+- [Spider database locali](https://drive.google.com/file/d/1coEVsCZq-Xvj9p2TnhBFoFTsY-UoYGmG/view),
+  collegati dal [README Lite](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/README.md).
+  Archivio: 456.643.204 byte; entry `f1.sqlite`.
+- [DBT_start_db.zip](https://drive.google.com/file/d/1N3f7BSWC4foj-V-1C9n8M2XmgV7FOcqL/view),
+  collegato dal [README DBT](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/README.md).
+  Archivio: 377.819.033 byte; Last-Modified 19 dicembre 2024.
+  Entry: `shopify001/shopify.duckdb`, `quickbooks001/quickbooks.duckdb`,
+  `workday001/workday.duckdb`.
+
+I pesi degli archivi completi non sono quelli dei soli database selezionati:
+contengono anche altri esempi. Non sommarli alla tabella salvo voler conservare
+localmente tutti i pacchetti originali.
+
+Per confronto, l'archivio ufficiale `dbt_gold.zip` contiene file corrispondenti di
+22.032.384 byte (Shopify), 54.013.952 byte (QuickBooks) e 28.848.128 byte (Workday).
+Sono versioni di risultato del benchmark, non la base scelta per la tabella e non
+una previsione del consumo finale di ThothII.
+
+## Limiti
+
+Il totale esclude descrizioni, Evidence, CSV esportati, indici aggiuntivi, log,
+PostgreSQL, Qdrant, immagini Docker e modelli locali. La conversione può modificare
+sensibilmente l'occupazione. Non sono state estratte tutte le tabelle né contate
+le righe: il peso del file non prova che tutte le tabelle documentate siano popolate.
+La complessità di schema e dominio non implica grandi volumi nei dati dimostrativi.

docs/research/2026-09-27-spider2-dbt-evidence-candidates.md

@@ -0,0 +1,117 @@
+# Candidati Spider 2.0-DBT con documentazione di dominio
+
+Ricerca del 27 settembre 2026. Obiettivo: scegliere un database locale complesso,
+con materiale da curare come Source Evidence di ThothII. Non vengono usate
+domande del benchmark, SQL attesi o punteggi come criterio di selezione.
+
+## Raccomandazione
+
+**Shopify è il candidato da verificare per primo**, perché combina commercio,
+pagamenti, rimborsi, inventario e ordini con documentazione dei significati e
+delle misure. Offre inoltre un dominio diverso dal Financial BIRD già proposto.
+QuickBooks è una valida alternativa se si preferisce la contabilità; Workday
+se si preferiscono personale e storia organizzativa. Questa priorità è una
+valutazione per il progetto, non una classificazione ufficiale Spider.
+
+| Progetto Spider 2.0-DBT | Tabelle sorgente dichiarate | Coppie tabella/colonna descritte e distinte | Database locale indicato dal profilo |
+| --- | ---: | ---: | --- |
+| Shopify, `shopify001` | 34 | 578 | `shopify.duckdb` |
+| QuickBooks, `quickbooks001` | 40 | 426 | `quickbooks.duckdb` |
+| Workday, `workday001` | 21 | 436 | `workday.duckdb` |
+
+Conteggi ricavati analizzando i rispettivi YAML `sources[].tables[]` e le
+descrizioni delle colonne; **non sono un'ispezione delle tabelle materializzate
+nei file DuckDB**. Alcune tabelle possono essere opzionali. Shopify ha 581
+dichiarazioni di colonna, ma tre sono duplicate: `order.total_shipping_price_set`,
+`order_line.tax_code`, `order_line_refund.subtotal_set`. I conteggi comprendono
+anche metadati tecnici e riferimenti `doc(...)`: **non equivalgono a un numero
+di Evidence Unit**. Sono esclusi i pacchetti di utilità generica dbt.
+Fonti: [Shopify schema](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/shopify001/dbt_packages/shopify_source/models/src_shopify.yml),
+[QuickBooks schema](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/quickbooks001/dbt_packages/quickbooks_source/models/src_quickbooks.yml),
+[Workday schema](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/workday001/models/staging/src_workday.yml).
+
+## Shopify: commercio e operazioni
+
+Lo schema documenta ordini e righe d'ordine, clienti, prodotti e varianti,
+transazioni, rimborsi, rettifiche, spedizioni, imposte, sconti, inventario,
+sedi e checkout abbandonati. Le descrizioni specificano sia la granularità
+delle entità sia il significato dei campi. Esempi di materiale semanticamente
+utile: il subtotale è dopo gli sconti e prima di spedizione, imposte e mance;
+`processed_at` è la data usata nei report analitici; l'ID API dell'ordine è
+distinto dal numero mostrato al cliente; valuta del negozio e valuta presentata
+al cliente hanno ruoli distinti. Le tre dichiarazioni duplicate richiedono
+normalizzazione prima dell'importazione documentale.
+[Dizionario sorgente](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/shopify001/dbt_packages/shopify_source/models/src_shopify.yml).
+
+Il progetto aggiunge definizioni di modelli analitici, inclusi ordini, coorti
+clienti e aggregazioni giornaliere del negozio; il solo `models/shopify.yml`
+ne dichiara 10. Sono modelli dbt, da tenere distinti dalle 34 sorgenti e dalle
+tabelle fisiche effettivamente disponibili. Queste definizioni sono un secondo
+livello di materiale per Evidence su granularità e metriche.
+[Modelli analitici](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/shopify001/models/shopify.yml).
+
+Il profilo indica esplicitamente DuckDB, percorso `./shopify.duckdb`, schema
+`main`. Non è necessario collegare un negozio Shopify reale per leggere il
+database distribuito dal progetto.
+[Profilo](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/shopify001/profiles.yml).
+
+## QuickBooks: contabilità e documenti commerciali
+
+Le 40 sorgenti dichiarate coprono conti, clienti, fornitori, fatture e righe,
+pagamenti, depositi, acquisti, ordini, note di credito, trasferimenti e
+registrazioni contabili. Il dizionario definisce classificazioni dei conti e
+tipi delle righe fattura, distinguendo elementi di vendita, descrizione,
+sconto e subtotale.
+[Dizionario sorgente](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/quickbooks001/dbt_packages/quickbooks_source/models/src_quickbooks.yml).
+
+La documentazione del libro mastro contiene una regola esplicita utile come
+Evidence: l'importo aumenta il conto quando il tipo di movimento corrisponde
+al lato di incremento del conto, e lo diminuisce altrimenti. Definisce inoltre
+importi convertiti e saldi progressivi. `models/quickbooks.yml` dichiara 29
+modelli tra intermedi e analitici: non sono 29 ulteriori tabelle sorgente
+garantite. I due file di documentazione contengono complessivamente 120 blocchi
+`docs` (68 nel progetto, 52 nel pacchetto sorgente); anche qui sono definizioni
+da selezionare e curare, non 120 Evidence Unit già validate.
+[Modelli e regole contabili](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/quickbooks001/models/quickbooks.yml),
+[glossario progetto](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/quickbooks001/models/docs.md),
+[glossario sorgente](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/quickbooks001/dbt_packages/quickbooks_source/models/docs.md).
+
+Il profilo usa `./quickbooks.duckdb`.
+[Profilo](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/quickbooks001/profiles.yml).
+
+## Workday: personale, ruoli e storia organizzativa
+
+Le sorgenti documentate comprendono lavoratori, posizioni, famiglie
+professionali, organizzazioni, assegnazioni e diverse tabelle storiche.
+Il glossario contiene 409 blocchi `docs`; molti sono definizioni brevi di
+attributi, non regole articolate. Fra i concetti documentati figurano FTE
+retribuito e lavorato, stato attivo/cessato, compensi, date di assunzione e
+appartenenze organizzative. La complessità temporale e organizzativa è
+interessante, ma il glossario da solo non giustifica chiamarlo il candidato
+con più Evidence di qualità.
+[Sorgenti](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/workday001/models/staging/src_workday.yml),
+[glossario](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/workday001/models/docs.md).
+
+Il profilo usa `./workday.duckdb`.
+[Profilo](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/workday001/profiles.yml).
+
+## Download e prossimo controllo prima della scelta definitiva
+
+Il README ufficiale fornisce due download Google Drive. Lo script di setup
+attende `DBT_start_db.zip` e `dbt_gold.zip`, estrae i file DuckDB e li distribuisce
+nei progetti e nella suite di riferimento. Per ThothII va scelto consapevolmente
+il contenuto da usare come esempio: non occorre importare il meccanismo di
+valutazione del benchmark. Questa ricerca verifica la pubblicazione del
+percorso di download e la configurazione locale; **non verifica il download
+integrale, dimensioni, righe, licenza dei singoli dati o schema fisico**.
+[README](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/README.md),
+[setup ufficiale](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/setup.py).
+
+Prima di promettere il pacchetto di installazione occorre scaricare il
+candidato, confrontare tabelle e colonne reali con la documentazione,
+verificare copertura delle entità e consistenza dei dati, e scegliere quali
+definizioni diventino Source Evidence. Per PostgreSQL la conversione proposta
+è schema esplicito più dati esportati; CSV sarebbe un formato derivato.
+Vanno preservati tipi numerici, date, valute, valori nulli e contenuti
+strutturati eventualmente presenti, adattando le sole trasformazioni
+necessarie. Non è ancora stato implementato o testato alcun convertitore.

docs/research/2026-09-27-spider2-lite-evidence-candidates.md

@@ -0,0 +1,86 @@
+# Alternative Spider 2.0-Lite per database dimostrativi con Evidence
+
+Verifica del 27 settembre 2026. Il criterio è complessità del database e qualità
+della documentazione di dominio da curare in ThothII, non prestazioni sul benchmark
+né numero di domande pubblicate. Nessun database è stato installato.
+
+## Metodo e limiti
+
+Ispezionati DDL, metadati per tabella e documenti ufficiali in
+[Spider2](https://github.com/xlang-ai/Spider2), revisione osservata
+`cafb867313aab4e674652054198f383cf4018943`. I conteggi sotto sono delle tabelle
+dichiarate nei DDL e delle colonne nei JSON, non un'ispezione dei file SQLite.
+La [procedura ufficiale](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/README.md)
+offre un archivio dei database locali. I database cloud seguono un percorso diverso.
+
+## Candidati locali
+
+| Database | Tabelle / colonne nei metadati | Materiale semantico riscontrato | Valutazione |
+| --- | --- | --- | --- |
+| `E_commerce` | 11 / 70 | Documento RFM; documentazione originale Olist da integrare | Il più coerente dei candidati Lite esaminati per una demo aziendale, ma complessità media |
+| `complex_oracle` | 10 / 140 | Proiezione vendite e conversioni valutarie; dizionario originale Oracle SH da confrontare | Buon caso analitico, meno esteso relazionalmente |
+| `oracle_sql` | 38 / 124 | Documento sul rapporto vendite/media mobile e finestre temporali | Molte tabelle, documentazione semantica allegata troppo parziale |
+| `AdventureWorks` | 13 / 120 | Documentazione originale Microsoft, da riallineare al sottoinsieme Spider | Non confondere questo estratto con l'intero AdventureWorks |
+
+Conteggi ricavati dai DDL e JSON ufficiali: [E_commerce](https://github.com/xlang-ai/Spider2/tree/main/spider2-lite/resource/databases/sqlite/E_commerce),
+[complex_oracle](https://github.com/xlang-ai/Spider2/tree/main/spider2-lite/resource/databases/sqlite/complex_oracle),
+[oracle_sql](https://github.com/xlang-ai/Spider2/tree/main/spider2-lite/resource/databases/sqlite/oracle_sql),
+[AdventureWorks](https://github.com/xlang-ai/Spider2/tree/main/spider2-lite/resource/databases/sqlite/AdventureWorks).
+In tutti i JSON di questi quattro candidati, gli array `description` controllati
+sono vuoti: tipi e righe di esempio non costituiscono da soli un dizionario di dominio.
+
+### E_commerce
+
+Comprende ordini, righe d'ordine, pagamenti, recensioni, prodotti, clienti, venditori,
+geolocalizzazione e lead. Il [documento RFM](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/RFM.md)
+definisce recency, frequency, monetary e undici segmenti con regole di assegnazione.
+Sono fonti concrete di formule e regole, da rivedere e collegare allo schema.
+
+La [fonte originale Olist](https://www.kaggle.com/olistbr/brazilian-ecommerce/metadata)
+fornisce CSV e spiega una distinzione utile: `customer_id` identifica il cliente
+nel contesto dell'ordine, mentre `customer_unique_id` permette di riconoscere acquisti
+ripetuti della stessa persona. La distribuzione Olist di base contiene nove file;
+non equivale automaticamente alle undici tabelle Spider, che includono i lead.
+
+### complex_oracle
+
+Il [documento allegato](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/projection_calculation.md)
+descrive proiezione mensile delle vendite, crescita rispetto all'anno precedente,
+conversione in USD e gestione di cambi mancanti. Lo schema ha vendite e costi con
+dimensioni prodotto, cliente, calendario, canale, promozione e geografia.
+
+Nomi e struttura sono riconducibili al [Sales History di Oracle](https://github.com/oracle-samples/db-sample-schemas/tree/main/sales_history).
+Il suo script `sh_create.sql` contiene 88 commenti `COMMENT ON TABLE/COLUMN` e la
+distribuzione comprende CSV. È materiale aggiuntivo utile, ma ogni corrispondenza
+con lo schema Spider, incluse estensioni come `currency`, va verificata: non si
+deve importare la documentazione dell'originale come se descrivesse automaticamente
+ogni adattamento Spider.
+
+### oracle_sql
+
+Le tabelle coprono magazzino, ordini, confezioni annidate, vendite mensili e altri
+sottodomini eterogenei. Il [documento di calcolo](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/calculation_method.md)
+tratta tre aspetti: rapporto fra vendite e media mobile centrata, finestre di dodici
+mesi e limiti temporali per evitare effetti ai bordi. Questo non documenta in modo
+completo le altre parti del database: sconsigliato come scelta basata sulla sola
+abbondanza di tabelle.
+
+## Alternativa cloud con documentazione più ricca
+
+`ga4` offre tre documenti complementari: [dizionario degli eventi](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/ga4_obfuscated_sample_ecommerce.events.md),
+[dimensioni e metriche](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/ga4_dimensions_and_metrics.md)
+e [categorie delle pagine](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/ga4_page_category.md).
+Coprono campi annidati, classificazione dei canali e regole di interpretazione;
+sono più vicini al requisito semantico. Tuttavia la
+[distribuzione Spider è BigQuery](https://github.com/xlang-ai/Spider2/tree/main/spider2-lite/resource/databases/bigquery/ga4):
+molte tabelle sono partizioni giornaliere dello stesso schema logico. Il conteggio
+fisico non è una misura utile di complessità relazionale. Esportazione locale e
+adattamento PostgreSQL sarebbero lavoro aggiuntivo, non un semplice import SQLite.
+
+## Esito
+
+Nessuno dei quattro candidati SQLite esaminati combina da solo schema molto esteso
+e documentazione di dominio completa già pronta. Per cercare una scelta più forte,
+confrontare con i progetti Spider 2.0-DBT nella ricerca separata
+`2026-09-27-spider2-dbt-evidence-candidates.md`. I modelli documentati di dbt non
+vanno confusi con tabelle fisiche già presenti, né le librerie di utility con Evidence.

scripts/verify-workspace-install-docs.sh

@@ -79,7 +79,7 @@ verify_standalone_installation_guides() {
       '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' \
+      'tht setup --complete --profile local --shell-mode full --shell-default-locale en' \
       'scripts/verify-standalone-install.sh' \
       'Docker Hub' \
       'Gate A' \
@@ -99,8 +99,7 @@ verify_install_and_workspace_guides() {
   require_file "$workspace"
 
   for text in \
-    'tht setup --profile local' \
-    '--configure-only' \
+    'tht setup --complete --profile local' \
     'catalog-migrate' \
     'tht --installation /absolute/path/thothii-installation.yaml doctor --json'; do
     require_text "$install" "$text"

tools/tht/cmd/tht/main.go

@@ -40,9 +40,9 @@ When --installation is omitted, tht uses THOTHII_INSTALLATION or discovers one v
 descriptor in the current project tree.
 
 Commands:
-  setup [--configure-only] [--installation-id ID] [--profile local|server]
+  setup [--complete|--configure-only] [--installation-id ID] [--profile local|server]
       [--shell-mode full|embedded] [--shell-default-locale BCP47-TAG] [--shell-adapter omics-portal]
-                      Create or validate the local non-secret installation configuration.
+                      Create, validate, and optionally complete the local installation.
   installation migrate --output PATH --session-default PROVIDER/MODEL
       --embedding-id PROVIDER/MODEL --embedding-dimensions N
                       Create a review-only schema-v2 candidate from all three legacy model sources.
@@ -86,6 +86,10 @@ Commands:
                       Verify a terminal installation, remove stale lifecycle files, and clear maintenance.
   pi logs             Show the latest 200 sanitized core log lines (bounded; no follow mode).
   workspace inspect --workspace ID [--json]
+  workspace pull [--json]
+                       Pull and activate the configured workspace repository.
+  workspace test [--json]
+                       Test configured database, Evidence, Qdrant, and embedding connectivity.
   workspace evidence consolidate --workspace ID [--json]
   workspace evidence refresh --workspace ID [--json]
   workspace evidence decide --workspace ID --source-id SHA --revision SHA --decision keep|replace [--json]
@@ -400,6 +404,11 @@ func parseSetupArgs(args []string) (setup.Request, error) {
 		flag := args[0]
 		args = args[1:]
 		switch flag {
+		case "--complete":
+			if request.Complete {
+				return setup.Request{}, errors.New("--complete may be supplied once")
+			}
+			request.Complete = true
 		case "--configure-only":
 			if request.ConfigureOnly {
 				return setup.Request{}, errors.New("--configure-only may be supplied once")
@@ -484,6 +493,9 @@ func parseSetupArgs(args []string) (setup.Request, error) {
 			*target = value
 		}
 	}
+	if request.Complete && request.ConfigureOnly {
+		return setup.Request{}, errors.New("--complete and --configure-only cannot be combined")
+	}
 	return request, nil
 }
 
@@ -499,6 +511,9 @@ func writeRemovalTargets(outputWriter io.Writer, project string, targets []serve
 }
 
 func workspaceCommand(ctx context.Context, installation config.Installation, runner compose.Runner, args []string, secretValues []string, stdout, stderr io.Writer) int {
+	if len(args) > 0 && (args[0] == "pull" || args[0] == "test") {
+		return workspaceOperatorCommand(ctx, installation, runner, args, secretValues, stdout, stderr)
+	}
 	request, err := workspaceops.Parse(args)
 	if err != nil {
 		return commandUsageError(stderr, err.Error())
@@ -527,6 +542,51 @@ func workspaceCommand(ctx context.Context, installation config.Installation, run
 	}
 }
 
+func workspaceOperatorCommand(ctx context.Context, installation config.Installation, runner compose.Runner, args []string, secretValues []string, stdout, stderr io.Writer) int {
+	action := "workspace-" + args[0]
+	jsonMode := false
+	for _, arg := range args[1:] {
+		if arg != "--json" || jsonMode {
+			return commandUsageError(stderr, "workspace pull/test accepts only --json")
+		}
+		jsonMode = true
+	}
+	result, err := runner.Run(ctx, installation.ComposeArgs("exec", "-T", "core", "node", "dist/operator-command.js", action), nil)
+	if err != nil {
+		return writeResult(result, err, secretValues, stdout, stderr)
+	}
+	var payload struct {
+		Ready  bool   `json:"ready"`
+		Status string `json:"status"`
+	}
+	if err := json.Unmarshal([]byte(result.Stdout), &payload); err != nil {
+		fmt.Fprintln(stderr, "tht: workspace operator returned invalid JSON")
+		return 1
+	}
+	if jsonMode {
+		fmt.Fprintln(stdout, output.Sanitize(result.Stdout, secretValues))
+	} else {
+		fmt.Fprintf(stdout, "workspace %s: %s\n", args[0], output.Sanitize(workspaceOperatorSummary(payload), secretValues))
+	}
+	if !payload.Ready {
+		return 1
+	}
+	return 0
+}
+
+func workspaceOperatorSummary(payload struct {
+	Ready  bool   `json:"ready"`
+	Status string `json:"status"`
+}) string {
+	if payload.Status != "" {
+		return payload.Status
+	}
+	if payload.Ready {
+		return "ready"
+	}
+	return "failed"
+}
+
 func workspaceFailure(stderr io.Writer, err error, secretValues []string) int {
 	message := output.Sanitize(err.Error(), secretValues)
 	var operationErr *workspaceops.OperationError

tools/tht/internal/setup/files.go

@@ -3,6 +3,8 @@ package setup
 import (
 	"bufio"
 	"bytes"
+	"crypto/rand"
+	"encoding/hex"
 	"errors"
 	"fmt"
 	"io"
@@ -13,6 +15,7 @@ import (
 	"sort"
 	"strconv"
 	"strings"
+	"unicode"
 
 	"github.com/aritmolab/thothii/tools/tht/internal/config"
 	"github.com/aritmolab/thothii/tools/tht/internal/safeio"
@@ -26,6 +29,7 @@ const (
 )
 
 var installationIDPattern = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9_-]*$`)
+var secretBundleKeyPattern = regexp.MustCompile(`^[A-Z][A-Z0-9_]{0,127}$`)
 
 // atomicWriteNewFile is a seam for failure testing. Its implementation never replaces an existing
 // file and leaves no final target until all content is synced.
@@ -44,6 +48,7 @@ type answers struct {
 	secretsFile, piAuthFile          string
 	gitCredentialsFile, gitCAFile    string
 	gitSSHKeyFile, gitKnownHostsFile string
+	complete                         bool
 	createSecretTemplates            bool
 }
 
@@ -116,6 +121,11 @@ func EnsureFiles(request Request, input io.Reader, output io.Writer) (FilesResul
 	if err := validateOrCreateSecretFiles(values, output); err != nil {
 		return FilesResult{}, err
 	}
+	if values.complete {
+		if err := validateCompleteProtectedFiles(values); err != nil {
+			return FilesResult{}, err
+		}
+	}
 
 	created := make([]string, 0, 2)
 	cleanup := func() {
@@ -163,6 +173,27 @@ func collectAnswers(request Request, input io.Reader, output io.Writer, root str
 	value := answersFromRequest(request)
 	value.installationID = firstNonEmpty(request.InstallationID, os.Getenv("THT_SETUP_INSTALLATION_ID"), "local")
 	value.profile = firstNonEmpty(request.Profile, os.Getenv("THT_SETUP_PROFILE"), "local")
+	value.complete = request.Complete
+	if request.Complete {
+		// The complete path has one predictable protected directory. The user only fills the
+		// bundle and any repository credential that is genuinely required; catalog passwords
+		// are generated below and never appear in the questionnaire.
+		directory := filepath.Join(root, "deploy", value.installationID, "secrets")
+		value.workspaceBranch = firstNonEmpty(value.workspaceBranch, "main")
+		value.secretsFile = firstNonEmpty(value.secretsFile, filepath.Join(directory, "thothii.secrets"))
+		value.piAuthFile = firstNonEmpty(value.piAuthFile, filepath.Join(directory, "pi-auth.json"))
+		if request.NonInteractive {
+			value.workspaceAccess = firstNonEmpty(value.workspaceAccess, accessForRemote(value.workspaceRemote))
+			if value.workspaceAccess == "ssh" {
+				value.gitSSHKeyFile = firstNonEmpty(value.gitSSHKeyFile, filepath.Join(directory, "workspace-git-key"))
+				value.gitKnownHostsFile = firstNonEmpty(value.gitKnownHostsFile, filepath.Join(directory, "workspace-git-known-hosts"))
+			} else {
+				value.gitCredentialsFile = firstNonEmpty(value.gitCredentialsFile, filepath.Join(directory, "workspace-git-credentials"))
+				value.gitCAFile = firstNonEmpty(value.gitCAFile, filepath.Join(directory, "workspace-git-ca.pem"))
+			}
+		}
+		value.createSecretTemplates = true
+	}
 	if request.NonInteractive {
 		return requireNonInteractiveAnswers(value)
 	}
@@ -190,6 +221,18 @@ func collectAnswers(request Request, input io.Reader, output io.Writer, root str
 		return answers{}, err
 	}
 	directory := filepath.Join(root, "deploy", value.installationID, "secrets")
+	if request.Complete {
+		value.secretsFile = firstNonEmpty(value.secretsFile, filepath.Join(directory, "thothii.secrets"))
+		value.piAuthFile = firstNonEmpty(value.piAuthFile, filepath.Join(directory, "pi-auth.json"))
+		if value.workspaceAccess == "ssh" {
+			value.gitSSHKeyFile = firstNonEmpty(value.gitSSHKeyFile, filepath.Join(directory, "workspace-git-key"))
+			value.gitKnownHostsFile = firstNonEmpty(value.gitKnownHostsFile, filepath.Join(directory, "workspace-git-known-hosts"))
+		} else {
+			value.gitCredentialsFile = firstNonEmpty(value.gitCredentialsFile, filepath.Join(directory, "workspace-git-credentials"))
+			value.gitCAFile = firstNonEmpty(value.gitCAFile, filepath.Join(directory, "workspace-git-ca.pem"))
+		}
+		return value, nil
+	}
 	if value.secretsFile, err = prompt(scanner, output, "Secret file location", firstNonEmpty(value.secretsFile, filepath.Join(directory, "thothii.secrets"))); err != nil {
 		return answers{}, err
 	}
@@ -216,11 +259,15 @@ func collectAnswers(request Request, input io.Reader, output io.Writer, root str
 		return answers{}, missingErr
 	}
 	if len(missing) > 0 {
-		answer, promptErr := prompt(scanner, output, "Create blank secret-file templates for the missing locations? Type yes to confirm", "no")
-		if promptErr != nil {
-			return answers{}, promptErr
+		if request.Complete {
+			value.createSecretTemplates = true
+		} else {
+			answer, promptErr := prompt(scanner, output, "Create blank secret-file templates for the missing locations? Type yes to confirm", "no")
+			if promptErr != nil {
+				return answers{}, promptErr
+			}
+			value.createSecretTemplates = strings.EqualFold(answer, "yes")
 		}
-		value.createSecretTemplates = strings.EqualFold(answer, "yes")
 	}
 	return value, nil
 }
@@ -379,6 +426,13 @@ func render(root, descriptorPath string, value answers) ([]byte, []byte, error)
 	if value.llmURL != "" {
 		lines = append(lines, "THT_LLM_URL="+dotenvValue(value.llmURL))
 	}
+	if value.complete {
+		passwordDirectory := filepath.Dir(value.secretsFile)
+		lines = append(lines,
+			"THT_CATALOG_RUNTIME_PASSWORD_SOURCE="+dotenvValue(filepath.Join(passwordDirectory, "catalog-runtime-password")),
+			"THT_CATALOG_MIGRATOR_PASSWORD_SOURCE="+dotenvValue(filepath.Join(passwordDirectory, "catalog-migrator-password")),
+		)
+	}
 	if value.profile == "server" {
 		installationDirectory := filepath.Dir(descriptorPath)
 		lines = append(lines,
@@ -474,10 +528,7 @@ func validateOrCreateSecretFiles(value answers, output io.Writer) error {
 	if err != nil {
 		return err
 	}
-	if len(missing) == 0 {
-		return nil
-	}
-	if !value.createSecretTemplates {
+	if len(missing) > 0 && !value.createSecretTemplates {
 		return fmt.Errorf("secret files are missing: %s; create them yourself or explicitly confirm blank secret-file templates", strings.Join(missing, ", "))
 	}
 	for _, path := range missing {
@@ -489,6 +540,104 @@ func validateOrCreateSecretFiles(value answers, output io.Writer) error {
 		}
 		fmt.Fprintf(output, "Created blank secret-file template: %s\n", path)
 	}
+	if value.complete {
+		for _, path := range catalogPasswordPaths(value) {
+			exists, err := inspectExistingSecretFile(path)
+			if err != nil {
+				return err
+			}
+			if exists {
+				continue
+			}
+			contents, err := generatedCatalogPassword()
+			if err != nil {
+				return fmt.Errorf("generate catalog password: %w", err)
+			}
+			if err := atomicWriteNewFile(path, contents, 0o600); err != nil {
+				return fmt.Errorf("create catalog password %s: %w", path, err)
+			}
+			fmt.Fprintf(output, "Created generated catalog password file: %s\n", path)
+		}
+	}
+	return nil
+}
+
+func catalogPasswordPaths(value answers) []string {
+	directory := filepath.Dir(value.secretsFile)
+	return []string{
+		filepath.Join(directory, "catalog-runtime-password"),
+		filepath.Join(directory, "catalog-migrator-password"),
+	}
+}
+
+func generatedCatalogPassword() ([]byte, error) {
+	value := make([]byte, 32)
+	if _, err := rand.Read(value); err != nil {
+		return nil, errors.New("secure random source is unavailable")
+	}
+	return []byte(hex.EncodeToString(value) + "\n"), nil
+}
+
+func validateCompleteProtectedFiles(value answers) error {
+	if err := validateSecretBundle(value.secretsFile); err != nil {
+		return err
+	}
+	// The generated catalog deliberately uses Pi's built-in provider. A syntactically empty
+	// auth store would let Docker start only to fail at the first provider check, so catch it
+	// before any image is built. Other model providers can be selected later in the descriptor.
+	contents, err := safeio.ReadCanonicalRegular(value.piAuthFile, maxSecretBytes)
+	if err != nil || strings.TrimSpace(string(contents)) == "" || strings.TrimSpace(string(contents)) == "{}" {
+		return fmt.Errorf("complete setup requires usable Pi credentials in %s", value.piAuthFile)
+	}
+	if value.workspaceAccess == "ssh" {
+		for name, path := range map[string]string{
+			"workspace Git SSH key":     value.gitSSHKeyFile,
+			"workspace Git known-hosts": value.gitKnownHostsFile,
+		} {
+			contents, readErr := safeio.ReadCanonicalRegular(path, maxSecretBytes)
+			if readErr != nil || strings.TrimSpace(string(contents)) == "" {
+				return fmt.Errorf("complete setup requires usable %s in %s", name, path)
+			}
+		}
+	} else {
+		for name, path := range map[string]string{
+			"workspace Git credentials": value.gitCredentialsFile,
+			"workspace Git CA":          value.gitCAFile,
+		} {
+			contents, readErr := safeio.ReadCanonicalRegular(path, maxSecretBytes)
+			if readErr != nil || strings.TrimSpace(string(contents)) == "" {
+				return fmt.Errorf("complete setup requires usable %s in %s", name, path)
+			}
+		}
+	}
+	return nil
+}
+
+func validateSecretBundle(path string) error {
+	contents, err := safeio.ReadCanonicalRegular(path, maxSecretBytes)
+	if err != nil {
+		return fmt.Errorf("complete setup cannot read the secret bundle %s", path)
+	}
+	seen := make(map[string]struct{})
+	for lineNumber, raw := range strings.Split(string(contents), "\n") {
+		line := strings.TrimSuffix(raw, "\r")
+		trimmed := strings.TrimSpace(line)
+		if trimmed == "" || strings.HasPrefix(trimmed, "#") {
+			continue
+		}
+		key, secret, found := strings.Cut(line, "=")
+		invalid := !found || !secretBundleKeyPattern.MatchString(key) || strings.TrimSpace(key) != key ||
+			secret == "" || strings.TrimSpace(secret) != secret ||
+			strings.Contains(strings.ToLower(secret), "replace-me") ||
+			strings.IndexFunc(secret, unicode.IsSpace) >= 0
+		if invalid {
+			return fmt.Errorf("complete setup found an invalid secret bundle entry at line %d", lineNumber+1)
+		}
+		if _, duplicate := seen[key]; duplicate {
+			return fmt.Errorf("complete setup found a duplicate secret bundle key %s", key)
+		}
+		seen[key] = struct{}{}
+	}
 	return nil
 }
 

tools/tht/internal/setup/files_test.go

@@ -207,6 +207,50 @@ func TestEnsureFilesRequiresExplicitNonInteractiveAnswers(t *testing.T) {
 	}
 }
 
+func TestCompleteSetupCreatesProtectedPlaceholdersThenRequiresUsableCredentials(t *testing.T) {
+	root := newProject(t, "complete setup")
+	for name, value := range map[string]string{
+		"THT_SETUP_WORKSPACE_REMOTE": "git@git.example.invalid:team/workspaces.git",
+		"THT_SETUP_WORKSPACE_BRANCH": "main",
+		"THT_SETUP_WORKSPACE_ACCESS": "ssh",
+	} {
+		t.Setenv(name, value)
+	}
+	request := Request{ProjectRoot: root, InstallationID: "local", Profile: "local", Complete: true, NonInteractive: true}
+	if _, err := EnsureFiles(request, strings.NewReader(""), ioDiscard{}); err == nil || !strings.Contains(err.Error(), "usable Pi credentials") {
+		t.Fatalf("first complete setup error = %v, want the placeholder guidance", err)
+	}
+	secretRoot := filepath.Join(root, "deploy", "local", "secrets")
+	for path, contents := range map[string]string{
+		filepath.Join(secretRoot, "pi-auth.json"):              "{\"deepseek\":{\"apiKey\":\"configured\"}}\n",
+		filepath.Join(secretRoot, "workspace-git-key"):         "private-key\n",
+		filepath.Join(secretRoot, "workspace-git-known-hosts"): "git.example.invalid ssh-ed25519 AAAA\n",
+	} {
+		if err := os.WriteFile(path, []byte(contents), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	result, err := EnsureFiles(request, strings.NewReader(""), ioDiscard{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	environment, err := os.ReadFile(result.EnvironmentPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, name := range []string{"THT_CATALOG_RUNTIME_PASSWORD_SOURCE", "THT_CATALOG_MIGRATOR_PASSWORD_SOURCE"} {
+		if !strings.Contains(string(environment), name+"=") {
+			t.Fatalf("complete environment misses %s: %s", name, environment)
+		}
+	}
+	for _, name := range []string{"catalog-runtime-password", "catalog-migrator-password"} {
+		contents, readErr := os.ReadFile(filepath.Join(secretRoot, name))
+		if readErr != nil || len(strings.TrimSpace(string(contents))) < 32 {
+			t.Fatalf("generated catalog password %s is unavailable or too short", name)
+		}
+	}
+}
+
 func TestEnsureFilesIncludesServerStorageLocations(t *testing.T) {
 	requireProjectedServerTestHost(t)
 	root := newProject(t, "server profile")

tools/tht/internal/setup/request.go

@@ -1,12 +1,15 @@
 // Package setup creates the local, non-secret configuration selected by tht setup.
 package setup
 
-// Request contains the stable setup-file inputs. Task 5 will use ConfigureOnly when it adds
-// Compose validation and lifecycle orchestration.
+// Request contains the stable setup-file inputs.
 type Request struct {
 	ProjectRoot    string
 	InstallationID string
 	Profile        string
+	// Complete runs the installation-only steps that are safe to automate: catalog migration,
+	// stack startup, and the initial workspace pull. It intentionally does not invent database
+	// bindings or credentials that belong to the installation operator.
+	Complete       bool
 	ConfigureOnly  bool
 	NonInteractive bool
 	Answers        Answers

tools/tht/internal/setup/run.go

@@ -3,6 +3,7 @@ package setup
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
@@ -35,7 +36,8 @@ type Result struct {
 }
 
 // Run validates the host, creates or validates non-secret configuration, and by default builds,
-// starts, and verifies the current checkout. ConfigureOnly stops after Compose rendering.
+// starts, and verifies the current checkout. Complete additionally migrates the Catalog and
+// imports the configured workspace repository. ConfigureOnly stops after Compose rendering.
 func Run(ctx context.Context, runner compose.Runner, request Request, input io.Reader, output io.Writer) (Result, error) {
 	if runner == nil {
 		return Result{}, errors.New("setup requires a Docker command runner")
@@ -71,13 +73,33 @@ func Run(ctx context.Context, runner compose.Runner, request Request, input io.R
 		fmt.Fprintf(output, "Configuration is ready: %s\n", result.DescriptorPath)
 		return result, nil
 	}
-	if err := service.Start(ctx, installation, runner, true); err != nil {
+	if request.Complete {
+		if err := runCompose(ctx, runner, installation, "build"); err != nil {
+			return Result{}, fmt.Errorf("setup image build: %w", err)
+		}
+		if err := runCompose(ctx, runner, installation, "up", "--detach", "catalog-db"); err != nil {
+			return Result{}, fmt.Errorf("setup Catalog database start: %w", err)
+		}
+		if err := runCompose(ctx, runner, installation,
+			"--profile", "catalog-maintenance", "run", "--rm", "catalog-migrate"); err != nil {
+			return Result{}, fmt.Errorf("setup Catalog migration: %w", err)
+		}
+	}
+	if err := service.Start(ctx, installation, runner, !request.Complete); err != nil {
 		if strings.Contains(err.Error(), "image build") {
 			return Result{}, fmt.Errorf("setup %w", err)
 		}
 		return Result{}, withStartupRecovery(fmt.Errorf("setup %w", err), recoveryService(err))
 	}
 	result.Built, result.Started, result.Healthy = true, true, true
+	if request.Complete {
+		if err := runOperator(ctx, runner, installation, "workspace-pull"); err != nil {
+			return Result{}, withStartupRecovery(fmt.Errorf("setup workspace import: %w", err), "core")
+		}
+		if err := runOperator(ctx, runner, installation, "pi-test"); err != nil {
+			return Result{}, withStartupRecovery(fmt.Errorf("setup LLM credential test: %w", err), "core")
+		}
+	}
 	report, err := doctor.Run(ctx, installation, runner)
 	if err != nil {
 		return Result{}, withStartupRecovery(fmt.Errorf("setup doctor: %w", err), "core")
@@ -85,6 +107,9 @@ func Run(ctx context.Context, runner compose.Runner, request Request, input io.R
 	if !report.OK {
 		return Result{}, withStartupRecovery(errors.New("setup doctor reported failed checks"), "core")
 	}
+	if request.Complete {
+		fmt.Fprintln(output, "Workspace repository pulled and activated; run 'tht workspace test' after configuring each workspace database.")
+	}
 	fmt.Fprintf(output, "ThothII is ready at %s\nInstallation descriptor: %s\nNext: tht status\n", frontendURL(installation), result.DescriptorPath)
 	return result, nil
 }
@@ -219,6 +244,25 @@ func runCompose(ctx context.Context, runner compose.Runner, installation config.
 	return nil
 }
 
+func runOperator(ctx context.Context, runner compose.Runner, installation config.Installation, action string) error {
+	result, err := runner.Run(ctx, installation.ComposeArgs(
+		"exec", "-T", "core", "node", "dist/operator-command.js", action,
+	), nil)
+	if err != nil {
+		if result.ExitCode != 0 {
+			return fmt.Errorf("Docker exited with status %d", result.ExitCode)
+		}
+		return err
+	}
+	var payload struct {
+		Ready *bool `json:"ready"`
+	}
+	if err := json.Unmarshal([]byte(result.Stdout), &payload); err != nil || payload.Ready == nil || !*payload.Ready {
+		return fmt.Errorf("operator action %s reported failure", action)
+	}
+	return nil
+}
+
 func composeFailure(result compose.Result, cause error) error {
 	if result.ExitCode != 0 {
 		return fmt.Errorf("Docker exited with status %d", result.ExitCode)

tools/tht/internal/setup/run_test.go

@@ -68,6 +68,34 @@ func TestRunConfigureOnlyStopsAfterRenderedConfiguration(t *testing.T) {
 	}
 }
 
+func TestRunCompleteMigratesCatalogPullsWorkspaceAndTestsLLM(t *testing.T) {
+	root, request := setupRunFixture(t, false)
+	request.Complete = true
+	secretRoot := filepath.Join(root, "deploy", "ci", "secrets")
+	for path, contents := range map[string]string{
+		filepath.Join(secretRoot, "pi-auth.json"):              "{\"deepseek\":{\"apiKey\":\"configured\"}}\n",
+		filepath.Join(secretRoot, "workspace-git-key"):         "private-key\n",
+		filepath.Join(secretRoot, "workspace-git-known-hosts"): "git.example.invalid ssh-ed25519 AAAA\n",
+	} {
+		if err := os.WriteFile(path, []byte(contents), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	runner := &setupRunner{health: []string{healthyServicesJSON}}
+	if _, err := Run(context.Background(), runner, request, strings.NewReader(""), io.Discard); err != nil {
+		t.Fatal(err)
+	}
+	want := []string{
+		"docker engine", "docker compose", "architecture", "compose config", "compose build",
+		"catalog db", "catalog migrate", "compose up", "health", "workspace pull", "pi doctor",
+		"doctor docker", "doctor compose", "compose config", "doctor config", "health",
+		"authentication", "core HTTP", "frontend HTTP", "workspace registry", "workflow doctor", "pi doctor",
+	}
+	if got := collapseStages(runner.stages); strings.Join(got, " | ") != strings.Join(want, " | ") {
+		t.Fatalf("complete setup stages = %v, want %v", got, want)
+	}
+}
+
 func TestRunConfiguresAndStaticallyValidatesLocalAuthBeforeComposeRender(t *testing.T) {
 	projectRoot, request := setupRunFixture(t, true)
 	passwordFile := filepath.Join(projectRoot, "initial-admin-password")
@@ -421,6 +449,10 @@ func setupStage(args []string) (string, compose.Result) {
 		return "architecture", compose.Result{Stdout: "arm64\n"}
 	case strings.HasSuffix(joined, " config --quiet"):
 		return "compose config", compose.Result{}
+	case strings.HasSuffix(joined, " up --detach catalog-db"):
+		return "catalog db", compose.Result{}
+	case strings.HasSuffix(joined, " --profile catalog-maintenance run --rm catalog-migrate"):
+		return "catalog migrate", compose.Result{}
 	case strings.HasSuffix(joined, " build"):
 		return "compose build", compose.Result{}
 	case strings.HasSuffix(joined, " up --detach --remove-orphans"):
@@ -433,6 +465,8 @@ func setupStage(args []string) (string, compose.Result) {
 		return "authentication", compose.Result{Stdout: `{"ready":true,"mode":"oidc","checks":[{"level":"info","code":"auth_ready","message":"Authentication is ready."}]}`}
 	case strings.Contains(joined, "exec -T core node dist/operator-command.js workflow-doctor"):
 		return "workflow doctor", compose.Result{Stdout: `{"ready":true,"workspaces":1}`}
+	case strings.Contains(joined, "operator-command.js workspace-pull"):
+		return "workspace pull", compose.Result{Stdout: `{"ready":true,"status":"succeeded"}`}
 	case strings.Contains(joined, "exec -T core curl -fsS --max-time 5 http://127.0.0.1:8787/health"):
 		return "core HTTP", compose.Result{}
 	case strings.Contains(joined, "exec -T frontend wget -q -T 5 -O /dev/null http://127.0.0.1:8080/"):