ThothII/search/search_index.json

{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"ThothII documentation \u00b6 ThothII turns a natural-language question into reviewed SQL. The model proposes; a human reviewer decides which interpretations, sources and results to accept. This is the public product manual. Start with the task you need to perform: I need to\u2026 Start here Understand the product and its boundaries What ThothII does Install on Mac, Windows through WSL2, or Linux Italian procedure \u00b7 English procedure Choose display mode and language Display mode and language Configure login Local accounts \u00b7 OIDC Configure model providers Model configuration Prepare a domain workspace Workspaces Configure databases and reviewed descriptions Database management Ask a question and review SQL User guide \u00b7 Workflow Maintain domain knowledge Evidence \u00b7 Memory Scope of this manual \u00b6 The manual covers the product, installation, use and administration. Architecture, code contracts, design decisions, implementation plans, test reports and site-specific deployment handoffs are developer/project material maintained in the repository; they are not pages of this site and are not included in its search index. The installation procedures distinguish checked documentation from platform and functional tests that still require execution. A clone does not transfer another installation's credentials, data or network access. The host-side tht command operates an installation. The Python workflow CLI inside the runtime is a separate internal interface; do not substitute its commands for the host installation procedure.","title":"Home"},{"location":"#thothii-documentation","text":"ThothII turns a natural-language question into reviewed SQL. The model proposes; a human reviewer decides which interpretations, sources and results to accept. This is the public product manual. Start with the task you need to perform: I need to\u2026 Start here Understand the product and its boundaries What ThothII does Install on Mac, Windows through WSL2, or Linux Italian procedure \u00b7 English procedure Choose display mode and language Display mode and language Configure login Local accounts \u00b7 OIDC Configure model providers Model configuration Prepare a domain workspace Workspaces Configure databases and reviewed descriptions Database management Ask a question and review SQL User guide \u00b7 Workflow Maintain domain knowledge Evidence \u00b7 Memory","title":"ThothII documentation"},{"location":"#scope-of-this-manual","text":"The manual covers the product, installation, use and administration. Architecture, code contracts, design decisions, implementation plans, test reports and site-specific deployment handoffs are developer/project material maintained in the repository; they are not pages of this site and are not included in its search index. The installation procedures distinguish checked documentation from platform and functional tests that still require execution. A clone does not transfer another installation's credentials, data or network access. The host-side tht command operates an installation. The Python workflow CLI inside the runtime is a separate internal interface; do not substitute its commands for the host installation procedure.","title":"Scope of this manual"},{"location":"evidence/","text":"Evidence: sources, preparation, and review \u00b6 This page describes the complete workspace Evidence lifecycle: where original material lives, how curated units are produced, when they become available at runtime, and what the author and reviewer are responsible for. Editable local Evidence \u00b6 E1 adds Curated Evidence v4 and a persistent local archive . The visible title and payload fields are authoritative Markdown. New manual units need no external source; consolidation records their curator and distinguishes later corrections from original documentary provenance. The core archive API creates immutable candidates and advances its active pointer only after successful indexing. E2 adds Administration \u2192 Evidence management , actual host file paths, complete browsing and filtering, and the installed tht workspace evidence consolidate --workspace <id> command. Edit files externally, consolidate to activate them, then review and run Git manually. Runtime consumes only the active local snapshot. The v4 contract describes host mounting, first conversion, failure recovery and Clear behavior. The local PSD preview has 35 converted and indexed units. E3 adds explicit import/refresh from local drafts and configured HTTP/S3 sources, durable current/proposed comparisons, and keep/replace decisions with activation and retry. See Import drafts and refresh sources . Workflow gate corrections remain the subsequent shared increment, X1. Existing repository publication path \u00b6 The remainder describes the legacy, uninitialized repository source path. Initialized v4 local archives use the lifecycle above; manual declarations need no source document. The workspace repository is the versioned source. ThothII reads it, validates it, and publishes an atomic generation. It does not modify, commit, or push the author's repository. Evidence becomes available to the workflow only when: the original material is in source/ ; the derived unit is in curated/ ; the manifest links the unit, source, and hash; validation finds no errors or unresolved review items; preprocessing builds and activates an indexed generation. A proposal generated during a session is not automatically published Evidence. The model may propose a formula or explanation, but a curator must import, review, and publish it in the repository before another session can retrieve it. Where the original source belongs \u00b6 For filesystem Evidence v2, the authoritative original source must be in the source/ directory of the workspace repository. curated/ contains the reviewed and indexed result, not the original material. <workspace-repository>/ \u251c\u2500\u2500 source/ # materiale originale, preservato \u2502 \u2514\u2500\u2500 <domain>/<file>.md \u251c\u2500\u2500 curated/ # reviewed Evidence Units \u2502 \u2514\u2500\u2500 <domain>/<unit>.md \u251c\u2500\u2500 manifest.yaml # preparation links, hashes, and metadata \u2514\u2500\u2500 example/ # examples and supporting material The workspace descriptor must declare evidence.schema_version: 2 and use exactly this configuration for a filesystem source: evidence: schema_version: 2 source: type: filesystem uri: \"<workspace.id>/evidence\" patterns: - \"curated/**/*.md\" The legacy configuration may expose source_root , such as ${THT_DOCS_ROOT} or /data . For the v2 structure, the runtime pattern must select only curated/**/*.md . Do not index source/ directly, mix source/ and curated/ , use broader globs, or include non-Markdown files. HTTP and S3 are separate adapters. They do not use the filesystem structure source/ and curated/ , but they must still provide stable provenance, without credentials in URIs, under the adapter-specific contract. What an editable curated unit contains \u00b6 New preparation produces unit schema v4. The first H1 contains its title; documented H2 sections contain the typed payload. A minimal manual unit is: --- schema_version: 4 id: evidence:order-key kind: domain language: en purposes: [sql_generation] --- # Order key ## Rule Join orders using the order number, financial year and company. Use tht evidence migrate <workspace-root> for deterministic legacy conversion. The conversion preserves typed content and initializes an archive baseline; it does not activate the local corpus. See the v4 contract for all eight kinds, provenance, file layout and the E1/E2 boundary. Legacy v3 representation \u00b6 Canonical Curated Evidence v3 hides canonical machine metadata in an HTML comment and renders the whole review surface as real Markdown. GitHub therefore shows no frontmatter table. The body layout is deterministic for each Evidence kind: prose uses sections and paragraphs, scopes and enum values use wrapping lists, formulas use fenced SQL, supporting excerpts use blockquotes, and unresolved review items use dedicated blocks. Long domain rules are split into readable paragraphs, labelled subsections, and lists at existing semicolon boundaries. Their exact original text remains canonical in an invisible marker, so the formatting cannot change their meaning or bytes. Preprocessing parses the unit first and builds semantic chunks from the typed payload. The vector store therefore receives the original rule text and not headings, list markers, or invisible presentation metadata. <!-- tht:metadata:<canonical metadata> --> # Fascia pediatrica > **Dominio** \u00b7 Italiano > > **Scopi:** Disambiguazione ## Ambito di applicazione ### Concetti - fascia pediatrica ## Regola La fascia pediatrica comprende i pazienti con et\u00e0 inferiore a 18 anni. ## Estratti di supporto > I pazienti sotto i 18 anni sono pediatrici. <details> <summary>Dettagli tecnici e provenienza</summary> - **ID:** `evidence:fascia-pediatrica` - **File sorgente:** `source/domain/paziente.md` </details> The actual files contain invisible tht: comments for canonical metadata and typed-field boundaries. Removing, duplicating, or desynchronizing them makes validation fail closed instead of silently ignoring content. Unit schemas v1 and v2 remain readable for compatibility, but newly prepared units use v4. Unit v3 remains readable as a conversion input. Curated units must be atomic, readable by a second reviewer, and supported by the source. Provenance references must lead back to the original file and the passage that supports the claim. Do not put secrets, tokens, passwords, or credentials in metadata or URIs. The modern canonical form also stores the Evidence kind, provenance, supporting excerpts, source_file , and source_sha256 . The canonical contract rejects unknown fields, mutable metadata, and URIs containing credentials. Identifiers must remain stable even when a unit's kind changes. Preparation: from source to active generation \u00b6 flowchart TD SRC[\"source/DOMAIN/*.md\\noriginal material\"] --> PREP[\"tht evidence prepare\\ncandidate preparation\"] PREP --> CAND[\"curated/DOMAIN/*.md\\nproposed or updated units\"] CAND --> VAL[\"tht evidence validate\\nstructure and link checks\"] VAL -->|errors or review items| FIX[\"Author corrections\\nand review\"] FIX --> PREP VAL -->|publishable| COMMIT[\"Commit del repository\\nauthoring clone\"] COMMIT --> ING[\"tht workspace preprocess run\\nnormalization and chunking\"] ING --> BM25[\"BM25 index\"] ING --> VEC[\"Embeddings and vector store\"] BM25 --> GEN[\"Candidate generation\"] VEC --> GEN GEN --> ACT[\"Replace active Evidence slice\"] ACT --> RUNTIME[\"Evidence retrieval in the workflow\"] Preparation can restructure changed sources, but it does not publish by itself. prepare produces a proposal and can identify the document involved in an error. validate does not write or publish. The curator publishes the revision. The complete workspace preprocessing command reads that exact revision and replaces the active Evidence slice. There is no application-level rollback; rerun complete preprocessing after correcting a failure. Runtime retrieval is hybrid. The dense branch uses embeddings, the BM25 branch uses lexical search, and deterministic fusion orders the results. Evidence fragments live in the workspace reference collection together with Schema and relationships; runtime Memory and solved questions live in a separate memory collection. The published unit keeps its provenance, which the model must cite when it uses the Evidence. Author responsibilities \u00b6 The author prepares the material and makes every unit verifiable. The author must: put the original material in source/ without changing its meaning during curation; split the content into atomic units, with one rule or definition per unit when possible; assign a stable identifier and a clear title; provide provenance, tables, and related concepts when known; keep the text in the workspace language; separate facts, rules, examples, formulas, and limits; include excerpts that support the unit without extending the conclusion beyond the source; run tht evidence prepare and tht evidence validate ; resolve every error and review item before proposing a commit; give the reviewer the necessary context, including source changes and the reason for any rename or retirement. The author must not: write directly to the active production corpus; treat a model proposal as a verified fact; delete an unsupported unit without recording its retirement or relink; put credentials in metadata, files, or provenance URLs; manually change manifests, hashes, or generations to make validation pass. Reviewer responsibilities \u00b6 The reviewer does not approve text merely because it is clear. The reviewer checks the relationship between source, unit, and intended use. For each unit, the reviewer must check: the cited source exists in the reviewed revision; the excerpt actually supports the claim; the unit does not combine incompatible rules or independent concepts; tables, columns, and concepts are identified correctly; the identifier is stable and does not duplicate another unit; the text distinguishes the definition, condition, exception, and example; it contains no sensitive information or details absent from the source; retrieval evaluation covers relevant queries and does not hide empty results. The reviewer can approve, request changes, reject, retire, or relink a unit to a new source. Retirement must be explicit. A relink must name the new file and leave a verifiable record of the decision. Approval does not publish immediately: the repository must pass validation and the generation must pass evaluation before activation. Available commands \u00b6 Authoring commands operate on the workspace repository and do not publish directly. # Prepare changed sources. Does not commit or publish. tht evidence prepare <workspace-root> # Reprocess all sources with the installed pipeline. tht evidence prepare <workspace-root> --upgrade # Rewrite legacy v1/v2 units as table-free v3 Markdown without model calls. tht evidence migrate <workspace-root> # Validate structure, manifest, links, and review items. tht evidence validate <workspace-root> # Return JSON for CI or automated tools. tht evidence validate <workspace-root> --json # Evaluate retrieval on a generation or the active generation. tht evidence evaluate <workspace-root> --config <workspace-config> tht evidence evaluate <workspace-root> --config <workspace-config> --generation <id> --json # Resolve a unit without publishing: retire it or link it to a new source. tht evidence resolve <workspace-root> evidence:<id> --retire tht evidence resolve <workspace-root> evidence:<id> --source source/domain/nuovo.md # Materialize Catalog-derived schema/LSH and the revision-pinned Evidence in one run. tht --installation <absolute>/thothii-installation.yaml \\ workspace preprocess run --workspace <workspace-id> evidence prepare , evidence migrate , evidence validate , and evidence resolve are authoring operations and require the repository path. Runtime publication is available only through the complete host-side workspace preprocess run ; there is no public Evidence-only preprocessing command. Exit codes are part of the operating contract: evidence validate returns 0 when the corpus is publishable, 1 for validation errors, and 3 when only review items or orphaned units remain. With --json , stdout must contain valid JSON only. Formulas and session proposals \u00b6 Formulas use a format distinct from document Evidence. A formula proposed during a session may be cited in the current proposal, but it does not enter the runtime corpus, receive a usable evidence: ID, or write to the repository. To become published, it must follow the same import, review, and preprocessing path as other units. Contract references \u00b6 Workspace Evidence v3 contract Preprocessing CLI contract","title":"Evidence"},{"location":"evidence/#evidence-sources-preparation-and-review","text":"This page describes the complete workspace Evidence lifecycle: where original material lives, how curated units are produced, when they become available at runtime, and what the author and reviewer are responsible for.","title":"Evidence: sources, preparation, and review"},{"location":"evidence/#editable-local-evidence","text":"E1 adds Curated Evidence v4 and a persistent local archive . The visible title and payload fields are authoritative Markdown. New manual units need no external source; consolidation records their curator and distinguishes later corrections from original documentary provenance. The core archive API creates immutable candidates and advances its active pointer only after successful indexing. E2 adds Administration \u2192 Evidence management , actual host file paths, complete browsing and filtering, and the installed tht workspace evidence consolidate --workspace <id> command. Edit files externally, consolidate to activate them, then review and run Git manually. Runtime consumes only the active local snapshot. The v4 contract describes host mounting, first conversion, failure recovery and Clear behavior. The local PSD preview has 35 converted and indexed units. E3 adds explicit import/refresh from local drafts and configured HTTP/S3 sources, durable current/proposed comparisons, and keep/replace decisions with activation and retry. See Import drafts and refresh sources . Workflow gate corrections remain the subsequent shared increment, X1.","title":"Editable local Evidence"},{"location":"evidence/#existing-repository-publication-path","text":"The remainder describes the legacy, uninitialized repository source path. Initialized v4 local archives use the lifecycle above; manual declarations need no source document. The workspace repository is the versioned source. ThothII reads it, validates it, and publishes an atomic generation. It does not modify, commit, or push the author's repository. Evidence becomes available to the workflow only when: the original material is in source/ ; the derived unit is in curated/ ; the manifest links the unit, source, and hash; validation finds no errors or unresolved review items; preprocessing builds and activates an indexed generation. A proposal generated during a session is not automatically published Evidence. The model may propose a formula or explanation, but a curator must import, review, and publish it in the repository before another session can retrieve it.","title":"Existing repository publication path"},{"location":"evidence/#where-the-original-source-belongs","text":"For filesystem Evidence v2, the authoritative original source must be in the source/ directory of the workspace repository. curated/ contains the reviewed and indexed result, not the original material. <workspace-repository>/ \u251c\u2500\u2500 source/ # materiale originale, preservato \u2502 \u2514\u2500\u2500 <domain>/<file>.md \u251c\u2500\u2500 curated/ # reviewed Evidence Units \u2502 \u2514\u2500\u2500 <domain>/<unit>.md \u251c\u2500\u2500 manifest.yaml # preparation links, hashes, and metadata \u2514\u2500\u2500 example/ # examples and supporting material The workspace descriptor must declare evidence.schema_version: 2 and use exactly this configuration for a filesystem source: evidence: schema_version: 2 source: type: filesystem uri: \"<workspace.id>/evidence\" patterns: - \"curated/**/*.md\" The legacy configuration may expose source_root , such as ${THT_DOCS_ROOT} or /data . For the v2 structure, the runtime pattern must select only curated/**/*.md . Do not index source/ directly, mix source/ and curated/ , use broader globs, or include non-Markdown files. HTTP and S3 are separate adapters. They do not use the filesystem structure source/ and curated/ , but they must still provide stable provenance, without credentials in URIs, under the adapter-specific contract.","title":"Where the original source belongs"},{"location":"evidence/#what-an-editable-curated-unit-contains","text":"New preparation produces unit schema v4. The first H1 contains its title; documented H2 sections contain the typed payload. A minimal manual unit is: --- schema_version: 4 id: evidence:order-key kind: domain language: en purposes: [sql_generation] --- # Order key ## Rule Join orders using the order number, financial year and company. Use tht evidence migrate <workspace-root> for deterministic legacy conversion. The conversion preserves typed content and initializes an archive baseline; it does not activate the local corpus. See the v4 contract for all eight kinds, provenance, file layout and the E1/E2 boundary.","title":"What an editable curated unit contains"},{"location":"evidence/#legacy-v3-representation","text":"Canonical Curated Evidence v3 hides canonical machine metadata in an HTML comment and renders the whole review surface as real Markdown. GitHub therefore shows no frontmatter table. The body layout is deterministic for each Evidence kind: prose uses sections and paragraphs, scopes and enum values use wrapping lists, formulas use fenced SQL, supporting excerpts use blockquotes, and unresolved review items use dedicated blocks. Long domain rules are split into readable paragraphs, labelled subsections, and lists at existing semicolon boundaries. Their exact original text remains canonical in an invisible marker, so the formatting cannot change their meaning or bytes. Preprocessing parses the unit first and builds semantic chunks from the typed payload. The vector store therefore receives the original rule text and not headings, list markers, or invisible presentation metadata. <!-- tht:metadata:<canonical metadata> --> # Fascia pediatrica > **Dominio** \u00b7 Italiano > > **Scopi:** Disambiguazione ## Ambito di applicazione ### Concetti - fascia pediatrica ## Regola La fascia pediatrica comprende i pazienti con et\u00e0 inferiore a 18 anni. ## Estratti di supporto > I pazienti sotto i 18 anni sono pediatrici. <details> <summary>Dettagli tecnici e provenienza</summary> - **ID:** `evidence:fascia-pediatrica` - **File sorgente:** `source/domain/paziente.md` </details> The actual files contain invisible tht: comments for canonical metadata and typed-field boundaries. Removing, duplicating, or desynchronizing them makes validation fail closed instead of silently ignoring content. Unit schemas v1 and v2 remain readable for compatibility, but newly prepared units use v4. Unit v3 remains readable as a conversion input. Curated units must be atomic, readable by a second reviewer, and supported by the source. Provenance references must lead back to the original file and the passage that supports the claim. Do not put secrets, tokens, passwords, or credentials in metadata or URIs. The modern canonical form also stores the Evidence kind, provenance, supporting excerpts, source_file , and source_sha256 . The canonical contract rejects unknown fields, mutable metadata, and URIs containing credentials. Identifiers must remain stable even when a unit's kind changes.","title":"Legacy v3 representation"},{"location":"evidence/#preparation-from-source-to-active-generation","text":"flowchart TD SRC[\"source/DOMAIN/*.md\\noriginal material\"] --> PREP[\"tht evidence prepare\\ncandidate preparation\"] PREP --> CAND[\"curated/DOMAIN/*.md\\nproposed or updated units\"] CAND --> VAL[\"tht evidence validate\\nstructure and link checks\"] VAL -->|errors or review items| FIX[\"Author corrections\\nand review\"] FIX --> PREP VAL -->|publishable| COMMIT[\"Commit del repository\\nauthoring clone\"] COMMIT --> ING[\"tht workspace preprocess run\\nnormalization and chunking\"] ING --> BM25[\"BM25 index\"] ING --> VEC[\"Embeddings and vector store\"] BM25 --> GEN[\"Candidate generation\"] VEC --> GEN GEN --> ACT[\"Replace active Evidence slice\"] ACT --> RUNTIME[\"Evidence retrieval in the workflow\"] Preparation can restructure changed sources, but it does not publish by itself. prepare produces a proposal and can identify the document involved in an error. validate does not write or publish. The curator publishes the revision. The complete workspace preprocessing command reads that exact revision and replaces the active Evidence slice. There is no application-level rollback; rerun complete preprocessing after correcting a failure. Runtime retrieval is hybrid. The dense branch uses embeddings, the BM25 branch uses lexical search, and deterministic fusion orders the results. Evidence fragments live in the workspace reference collection together with Schema and relationships; runtime Memory and solved questions live in a separate memory collection. The published unit keeps its provenance, which the model must cite when it uses the Evidence.","title":"Preparation: from source to active generation"},{"location":"evidence/#author-responsibilities","text":"The author prepares the material and makes every unit verifiable. The author must: put the original material in source/ without changing its meaning during curation; split the content into atomic units, with one rule or definition per unit when possible; assign a stable identifier and a clear title; provide provenance, tables, and related concepts when known; keep the text in the workspace language; separate facts, rules, examples, formulas, and limits; include excerpts that support the unit without extending the conclusion beyond the source; run tht evidence prepare and tht evidence validate ; resolve every error and review item before proposing a commit; give the reviewer the necessary context, including source changes and the reason for any rename or retirement. The author must not: write directly to the active production corpus; treat a model proposal as a verified fact; delete an unsupported unit without recording its retirement or relink; put credentials in metadata, files, or provenance URLs; manually change manifests, hashes, or generations to make validation pass.","title":"Author responsibilities"},{"location":"evidence/#reviewer-responsibilities","text":"The reviewer does not approve text merely because it is clear. The reviewer checks the relationship between source, unit, and intended use. For each unit, the reviewer must check: the cited source exists in the reviewed revision; the excerpt actually supports the claim; the unit does not combine incompatible rules or independent concepts; tables, columns, and concepts are identified correctly; the identifier is stable and does not duplicate another unit; the text distinguishes the definition, condition, exception, and example; it contains no sensitive information or details absent from the source; retrieval evaluation covers relevant queries and does not hide empty results. The reviewer can approve, request changes, reject, retire, or relink a unit to a new source. Retirement must be explicit. A relink must name the new file and leave a verifiable record of the decision. Approval does not publish immediately: the repository must pass validation and the generation must pass evaluation before activation.","title":"Reviewer responsibilities"},{"location":"evidence/#available-commands","text":"Authoring commands operate on the workspace repository and do not publish directly. # Prepare changed sources. Does not commit or publish. tht evidence prepare <workspace-root> # Reprocess all sources with the installed pipeline. tht evidence prepare <workspace-root> --upgrade # Rewrite legacy v1/v2 units as table-free v3 Markdown without model calls. tht evidence migrate <workspace-root> # Validate structure, manifest, links, and review items. tht evidence validate <workspace-root> # Return JSON for CI or automated tools. tht evidence validate <workspace-root> --json # Evaluate retrieval on a generation or the active generation. tht evidence evaluate <workspace-root> --config <workspace-config> tht evidence evaluate <workspace-root> --config <workspace-config> --generation <id> --json # Resolve a unit without publishing: retire it or link it to a new source. tht evidence resolve <workspace-root> evidence:<id> --retire tht evidence resolve <workspace-root> evidence:<id> --source source/domain/nuovo.md # Materialize Catalog-derived schema/LSH and the revision-pinned Evidence in one run. tht --installation <absolute>/thothii-installation.yaml \\ workspace preprocess run --workspace <workspace-id> evidence prepare , evidence migrate , evidence validate , and evidence resolve are authoring operations and require the repository path. Runtime publication is available only through the complete host-side workspace preprocess run ; there is no public Evidence-only preprocessing command. Exit codes are part of the operating contract: evidence validate returns 0 when the corpus is publishable, 1 for validation errors, and 3 when only review items or orphaned units remain. With --json , stdout must contain valid JSON only.","title":"Available commands"},{"location":"evidence/#formulas-and-session-proposals","text":"Formulas use a format distinct from document Evidence. A formula proposed during a session may be cited in the current proposal, but it does not enter the runtime corpus, receive a usable evidence: ID, or write to the repository. To become published, it must follow the same import, review, and preprocessing path as other units.","title":"Formulas and session proposals"},{"location":"evidence/#contract-references","text":"Workspace Evidence v3 contract Preprocessing CLI contract","title":"Contract references"},{"location":"guida-utente/","text":"User guide: from question to validated SQL \u00b6 This guide is for a reviewer using a configured ThothII installation. Installation, workspace publication, preprocessing, and database administration are separate paths; links to them are at the end of this page. Standalone or inside Omics \u00b6 In full mode, ThothII has its own red header. Sign in using the installation's local account or the configured identity provider. The header lets you select English/Italian, light/dark, and fullscreen; Esc exits fullscreen. Open the user name menu to log out of ThothII. OIDC logout does not necessarily log out other applications using the same provider. In embedded mode, first sign in to Omics and choose Datamart Builder in its left menu. ThothII opens with that authenticated identity: there is no second login or duplicate header. Use Omics's language, theme, fullscreen and logout controls. If portal access expires, return to Omics, sign in and reopen the page. The Mac starts in English unless the browser remembers another choice. Changing the UI language affects labels, not saved domain content. A new session takes the selected language for the model's questions and reviewer choices; an existing session retains its saved language when resumed. Omics's language change reloads the page: confirm or cancel any unsaved-work warning. Reopening the saved session selection shows documents; it does not automatically restart generation. Before creating a session \u00b6 An administrator must have selected a workspace and configured the installation-wide provider, model, and thinking settings. The new-question form deliberately asks only for the question. The workspace is a pinned Git revision. A subsequent workspace update cannot alter a session already created from an earlier revision. If a workspace cannot reach its configured runtime DWH, new sessions are refused before any session state is written. Create and review a session \u00b6 Sign in and select Session ( Sessione in Italian). If a session is already open and unfinished, this returns to it without restarting it. Otherwise it opens a new question; no session is created until you submit that question. Enter a precise business question, including the relevant time period and desired output. For example: \u201cList patients discharged in the last 30 days, with ward and discharge date.\u201d Review each gate and make the decision requested by the widget. A choice with a decision payload can persist immediately; a multi-choice widget records each selected decision; a confirmation widget approves an artifact or phase. Inspect the generated artifacts, especially schema linking, CTEs, and final SQL. The final SQL is available only after the F7 review gate. At F8, decide whether a datamart is requested. This is distinct from approving the SQL. The workflow phases are fixed: Phase What is reviewed F1\u2013F3 clarification, reusable Memory, and the rewritten question F4\u2013F5 proposed tables, columns, Evidence, then their summary F6 a CTE plan or an explicit skip F7 sql_final.sql F8 the datamart request or refusal Resume, archive, and the meaning of saved state \u00b6 In Administration, the dot beside Workspace is green when readiness is confirmed and red otherwise. Hover the button for the exact state; assistive technology receives the same description. Select Workspace to inspect preparation. The session sidebar has two accordion sections: Active sessions and Archive , both initially closed. Only their headers appear below the scope tabs. Inside each nonempty list, Select all selects only that list; its delete action also applies only to the selected sessions in that list. The other list's selection is preserved. Opening a section closes the other; clicking the open section closes it too. Empty lists show only \"No sessions yet.\" Long lists scroll inside their own panels. Here active means not archived, not necessarily a running model process. Existing groups and session actions remain inside those sections. The sidebar lists sessions and their current lifecycle. Resuming returns to the last incomplete phase. A finalized or archived session cannot be resumed. The source of truth is the workspace session directory: session_manifest.yaml , phase artifacts, and review_decisions.jsonl . The visible activity stream is rebuilt from live SSE events and is not a transcript store. Therefore a decision or artifact that has not been persisted did not happen from the workflow\u2019s point of view. Choose the correct neighbouring path \u00b6 To prepare, update, validate, or preprocess a workspace, use Workspace operations . To create a database configuration, refresh its physical schema, or generate catalog descriptions, use Database management . To author material the workflow can retrieve, use Evidence . A proposal from a session does not become Evidence automatically: a curator must review and publish it in Git. For login and access recovery, use local authentication or OIDC authentication for full, or contact the portal administrator for embedded/upstream access .","title":"User guide"},{"location":"guida-utente/#user-guide-from-question-to-validated-sql","text":"This guide is for a reviewer using a configured ThothII installation. Installation, workspace publication, preprocessing, and database administration are separate paths; links to them are at the end of this page.","title":"User guide: from question to validated SQL"},{"location":"guida-utente/#standalone-or-inside-omics","text":"In full mode, ThothII has its own red header. Sign in using the installation's local account or the configured identity provider. The header lets you select English/Italian, light/dark, and fullscreen; Esc exits fullscreen. Open the user name menu to log out of ThothII. OIDC logout does not necessarily log out other applications using the same provider. In embedded mode, first sign in to Omics and choose Datamart Builder in its left menu. ThothII opens with that authenticated identity: there is no second login or duplicate header. Use Omics's language, theme, fullscreen and logout controls. If portal access expires, return to Omics, sign in and reopen the page. The Mac starts in English unless the browser remembers another choice. Changing the UI language affects labels, not saved domain content. A new session takes the selected language for the model's questions and reviewer choices; an existing session retains its saved language when resumed. Omics's language change reloads the page: confirm or cancel any unsaved-work warning. Reopening the saved session selection shows documents; it does not automatically restart generation.","title":"Standalone or inside Omics"},{"location":"guida-utente/#before-creating-a-session","text":"An administrator must have selected a workspace and configured the installation-wide provider, model, and thinking settings. The new-question form deliberately asks only for the question. The workspace is a pinned Git revision. A subsequent workspace update cannot alter a session already created from an earlier revision. If a workspace cannot reach its configured runtime DWH, new sessions are refused before any session state is written.","title":"Before creating a session"},{"location":"guida-utente/#create-and-review-a-session","text":"Sign in and select Session ( Sessione in Italian). If a session is already open and unfinished, this returns to it without restarting it. Otherwise it opens a new question; no session is created until you submit that question. Enter a precise business question, including the relevant time period and desired output. For example: \u201cList patients discharged in the last 30 days, with ward and discharge date.\u201d Review each gate and make the decision requested by the widget. A choice with a decision payload can persist immediately; a multi-choice widget records each selected decision; a confirmation widget approves an artifact or phase. Inspect the generated artifacts, especially schema linking, CTEs, and final SQL. The final SQL is available only after the F7 review gate. At F8, decide whether a datamart is requested. This is distinct from approving the SQL. The workflow phases are fixed: Phase What is reviewed F1\u2013F3 clarification, reusable Memory, and the rewritten question F4\u2013F5 proposed tables, columns, Evidence, then their summary F6 a CTE plan or an explicit skip F7 sql_final.sql F8 the datamart request or refusal","title":"Create and review a session"},{"location":"guida-utente/#resume-archive-and-the-meaning-of-saved-state","text":"In Administration, the dot beside Workspace is green when readiness is confirmed and red otherwise. Hover the button for the exact state; assistive technology receives the same description. Select Workspace to inspect preparation. The session sidebar has two accordion sections: Active sessions and Archive , both initially closed. Only their headers appear below the scope tabs. Inside each nonempty list, Select all selects only that list; its delete action also applies only to the selected sessions in that list. The other list's selection is preserved. Opening a section closes the other; clicking the open section closes it too. Empty lists show only \"No sessions yet.\" Long lists scroll inside their own panels. Here active means not archived, not necessarily a running model process. Existing groups and session actions remain inside those sections. The sidebar lists sessions and their current lifecycle. Resuming returns to the last incomplete phase. A finalized or archived session cannot be resumed. The source of truth is the workspace session directory: session_manifest.yaml , phase artifacts, and review_decisions.jsonl . The visible activity stream is rebuilt from live SSE events and is not a transcript store. Therefore a decision or artifact that has not been persisted did not happen from the workflow\u2019s point of view.","title":"Resume, archive, and the meaning of saved state"},{"location":"guida-utente/#choose-the-correct-neighbouring-path","text":"To prepare, update, validate, or preprocess a workspace, use Workspace operations . To create a database configuration, refresh its physical schema, or generate catalog descriptions, use Database management . To author material the workflow can retrieve, use Evidence . A proposal from a session does not become Evidence automatically: a curator must review and publish it in Git. For login and access recovery, use local authentication or OIDC authentication for full, or contact the portal administrator for embedded/upstream access .","title":"Choose the correct neighbouring path"},{"location":"product-overview/","text":"What ThothII does \u00b6 ThothII helps turn a natural-language question into reviewed SQL. It is intended for people who know the meaning of their data and need to make the assumptions behind a query explicit. The model proposes; a human reviewer approves, corrects or rejects. From a question to a reusable result \u00b6 The eight-phase workflow clarifies the question, consults reusable knowledge, selects relevant Evidence and database objects, prepares a query plan, and produces SQL for review. Approved knowledge can be saved for later questions. Workspace: the domain context and its Evidence configuration. Database catalog: tables, columns, relationships and reviewed descriptions. Evidence: domain sources and rules with provenance that a reviewer can inspect. Memory: reusable clarifications, SQL rules, solved questions and explained errors. Session: the saved artifacts and decisions for one question, not a permanent chat transcript. Resuming a session uses its saved state. Model output is a proposal, not a guarantee of correctness: review the scope, assumptions, sources and SQL before relying on the result. What an installation includes \u00b6 The Docker stack includes the web application, its runtime, a PostgreSQL metadata/Memory catalog, Qdrant and the embedding service. A browser is the normal user interface; the host tht command is used to configure and operate the installation. The data warehouse and generative model endpoints are configured separately. Docker does not supply their credentials, network access or domain data. A standalone installation is therefore self-hosted, but is not automatically offline or independent of those services. Review data-access permissions and the model-provider configuration before using real data. Choose your next step \u00b6 Install on Mac, Windows through WSL2, or Linux: Italian or English manual procedure. Configure display mode and language , authentication and models . Prepare workspaces and databases . Start a reviewed question using the user guide . The installation guides state the platform tests still to complete. Availability of a procedure is not a certification that every target machine has been tested.","title":"Product overview"},{"location":"product-overview/#what-thothii-does","text":"ThothII helps turn a natural-language question into reviewed SQL. It is intended for people who know the meaning of their data and need to make the assumptions behind a query explicit. The model proposes; a human reviewer approves, corrects or rejects.","title":"What ThothII does"},{"location":"product-overview/#from-a-question-to-a-reusable-result","text":"The eight-phase workflow clarifies the question, consults reusable knowledge, selects relevant Evidence and database objects, prepares a query plan, and produces SQL for review. Approved knowledge can be saved for later questions. Workspace: the domain context and its Evidence configuration. Database catalog: tables, columns, relationships and reviewed descriptions. Evidence: domain sources and rules with provenance that a reviewer can inspect. Memory: reusable clarifications, SQL rules, solved questions and explained errors. Session: the saved artifacts and decisions for one question, not a permanent chat transcript. Resuming a session uses its saved state. Model output is a proposal, not a guarantee of correctness: review the scope, assumptions, sources and SQL before relying on the result.","title":"From a question to a reusable result"},{"location":"product-overview/#what-an-installation-includes","text":"The Docker stack includes the web application, its runtime, a PostgreSQL metadata/Memory catalog, Qdrant and the embedding service. A browser is the normal user interface; the host tht command is used to configure and operate the installation. The data warehouse and generative model endpoints are configured separately. Docker does not supply their credentials, network access or domain data. A standalone installation is therefore self-hosted, but is not automatically offline or independent of those services. Review data-access permissions and the model-provider configuration before using real data.","title":"What an installation includes"},{"location":"product-overview/#choose-your-next-step","text":"Install on Mac, Windows through WSL2, or Linux: Italian or English manual procedure. Configure display mode and language , authentication and models . Prepare workspaces and databases . Start a reviewed question using the user guide . The installation guides state the platform tests still to complete. Availability of a procedure is not a certification that every target machine has been tested.","title":"Choose your next step"},{"location":"skills/","text":"ThothII operating workflow \u00b6 ThothII guides every question through eight phases. The model proposes the work, the reviewer makes decisions at gates, and the system records persistent artifacts and decisions. flowchart LR Q[\"Question\"] --> F1[\"F1 Clarification\"] F1 --> F2[\"F2 Memory\"] F2 --> F3[\"F3 Rewriting\"] F3 --> F4[\"F4 Evidence\"] F4 --> F5[\"F5 Schema\"] F5 --> F6[\"F6 CTE plan\"] F6 --> F7[\"F7 SQL\"] F7 --> F8[\"F8 Promotion\"] F8 --> DONE[\"Finalized session\"] Workflow principles \u00b6 The model proposes; the reviewer approves, corrects, or rejects. The session ledger records every material decision. Persisted state is the source of truth. A phase advances only when its artifacts and gates are complete. Resume rebuilds context from persisted artifacts, not from the conversation. F1: clarification \u00b6 The system identifies the ambiguity most likely to change the meaning of the question and presents one decision at a time. Mutually exclusive interpretations use a single choice; multiple valid answers use a multiple choice. F2: Memory \u00b6 The system proposes Memory items that fit the question. Selected items enter the current session context; unselected items remain available for future questions. F3: rewriting \u00b6 The system rewrites the question explicitly using the approved clarifications. The reviewer checks the resulting question and its assumptions before continuing. F4: Evidence \u00b6 The system retrieves Evidence from the active corpus and presents citations and provenance. The reviewer decides which items apply to the question. F5: schema \u00b6 Tables, columns, relationships, and filters are linked to the approved meaning of the question. The summary closes the phase when the question, assumptions, and DWH elements are consistent. F6: CTE plan \u00b6 The query is broken into named CTEs with a purpose, dependencies, tables, filters, and output columns. The reviewer sees each step before the system produces the final SQL. F7: final SQL \u00b6 The system produces sql_final.sql , checks it against the approved plan, and presents the artifact to the reviewer. A correction can reopen the CTE plan without discarding decisions that remain valid. F8: Memory promotion \u00b6 At the end of the session, the system proposes reusable Memory cards, including the approved solved question. The reviewer selects and edits the additions or updates to retain in the workspace's Memory archive, or declines them all. The session is then finalized. Available gates \u00b6 Gate Use Single choice Only one interpretation can be valid Multiple choice Several items can be valid at the same time Artifact confirmation Approval of a document or phase result Phase confirmation Explicitly closes a phase Resume and reopening \u00b6 A resumed session returns to its last incomplete phase. Reopening invalidates only the decisions and artifacts that depend on the changed point; the rest of the work remains valid.","title":"Reviewed workflow"},{"location":"skills/#thothii-operating-workflow","text":"ThothII guides every question through eight phases. The model proposes the work, the reviewer makes decisions at gates, and the system records persistent artifacts and decisions. flowchart LR Q[\"Question\"] --> F1[\"F1 Clarification\"] F1 --> F2[\"F2 Memory\"] F2 --> F3[\"F3 Rewriting\"] F3 --> F4[\"F4 Evidence\"] F4 --> F5[\"F5 Schema\"] F5 --> F6[\"F6 CTE plan\"] F6 --> F7[\"F7 SQL\"] F7 --> F8[\"F8 Promotion\"] F8 --> DONE[\"Finalized session\"]","title":"ThothII operating workflow"},{"location":"skills/#workflow-principles","text":"The model proposes; the reviewer approves, corrects, or rejects. The session ledger records every material decision. Persisted state is the source of truth. A phase advances only when its artifacts and gates are complete. Resume rebuilds context from persisted artifacts, not from the conversation.","title":"Workflow principles"},{"location":"skills/#f1-clarification","text":"The system identifies the ambiguity most likely to change the meaning of the question and presents one decision at a time. Mutually exclusive interpretations use a single choice; multiple valid answers use a multiple choice.","title":"F1: clarification"},{"location":"skills/#f2-memory","text":"The system proposes Memory items that fit the question. Selected items enter the current session context; unselected items remain available for future questions.","title":"F2: Memory"},{"location":"skills/#f3-rewriting","text":"The system rewrites the question explicitly using the approved clarifications. The reviewer checks the resulting question and its assumptions before continuing.","title":"F3: rewriting"},{"location":"skills/#f4-evidence","text":"The system retrieves Evidence from the active corpus and presents citations and provenance. The reviewer decides which items apply to the question.","title":"F4: Evidence"},{"location":"skills/#f5-schema","text":"Tables, columns, relationships, and filters are linked to the approved meaning of the question. The summary closes the phase when the question, assumptions, and DWH elements are consistent.","title":"F5: schema"},{"location":"skills/#f6-cte-plan","text":"The query is broken into named CTEs with a purpose, dependencies, tables, filters, and output columns. The reviewer sees each step before the system produces the final SQL.","title":"F6: CTE plan"},{"location":"skills/#f7-final-sql","text":"The system produces sql_final.sql , checks it against the approved plan, and presents the artifact to the reviewer. A correction can reopen the CTE plan without discarding decisions that remain valid.","title":"F7: final SQL"},{"location":"skills/#f8-memory-promotion","text":"At the end of the session, the system proposes reusable Memory cards, including the approved solved question. The reviewer selects and edits the additions or updates to retain in the workspace's Memory archive, or declines them all. The session is then finalized.","title":"F8: Memory promotion"},{"location":"skills/#available-gates","text":"Gate Use Single choice Only one interpretation can be valid Multiple choice Several items can be valid at the same time Artifact confirmation Approval of a document or phase result Phase confirmation Explicitly closes a phase","title":"Available gates"},{"location":"skills/#resume-and-reopening","text":"A resumed session returns to its last incomplete phase. Reopening invalidates only the decisions and artifacts that depend on the changed point; the rest of the work remains valid.","title":"Resume and reopening"},{"location":"general/pi-configuration/","text":"Installation Model Catalog \u00b6 ThothII has one operator-authored model source: modelCatalog in deploy/<installation-id>/thothii-installation.yaml . It declares models used by interactive Pi sessions, metadata generation, and the internal embedding service. Workspace descriptors never declare providers, model allowlists, defaults, embeddings, dimensions, or vector-store settings. Do not edit deploy/pi/models.json , deploy/pi/settings.json , files under generated/ , or provider/model environment defaults. Those former sources are retired. Host instructions in Administration \u00b6 The Pi configuration navigation button opens Pi management . Its Host maintenance section selects the installation host's Linux, macOS, or Windows tab automatically; the browser's operating system does not affect it. Selecting another tab is still possible. The host CLI includes THT_HOST_PLATFORM in the generated Compose projection using the OS on which it runs. Generate projections on the destination host, not on another computer, and do not edit generated files. Without this projection (older deployments or native development), the backend reports its own OS; a Linux Docker container cannot discover whether the physical host is macOS or Windows. Run the updated host CLI's normal configuration reload on the destination installation to regenerate this information. Minimal catalog \u00b6 schemaVersion: 2 modelCatalog: defaults: interaction: zai/glm-5.3 embedding: id: ollama/qwen3-embedding:0.6b dimensions: 1024 providers: zai: endpoint: baseUrl: https://api.z.ai/api/coding/paas/v4 authentication: mode: secret_env apiKeyEnv: ZAI_API_KEY session: mode: openai_compatible metadataGeneration: litellmProvider: openai models: glm-5.3: label: GLM 5.3 session: reasoning: true contextWindow: 200000 maxTokens: 131072 metadataGeneration: {} Provider and model entries are maps. The keys form the canonical identity <provider-key>/<model-key> ; label is only display text. A model is eligible for a use only when it contains that use block: session makes it selectable for interactive sessions; metadataGeneration makes it selectable for description generation; embedding is a single installation-level model rather than a selectable list. defaults.interaction is the only LLM default, required once per installation, never per workspace. Core and Administration share the user's operational model choice. An explicit choice takes priority over the default and is remembered in this browser for the authenticated user and application mount. Switching workspace does not change the model. Browser-storage restrictions may limit remembering to the current visit; preferences do not synchronize across devices or change installation YAML. An unavailable remembered model is not silently replaced: select another configured model. When any metadata-generation models are configured, the default and the operational list must support both session and metadataGeneration . Entries for just one adapter may remain in the installation inventory, but are not selectable for global interaction. Core-only installations remain supported when no metadata-generation model is configured; Admin AI is then unavailable. The embedding model remains separate and is unaffected by the interaction selector. New sessions record the selected model in their manifest. Resume retains the session's workspace and revision, but uses the current global model (the installation default for clients that omit a model). Historical manifest model fields are not rewritten by resume. Archived/finalized sessions remain read-only. Required operator verification for every model \u00b6 Catalog validation checks configuration, not model behavior. Before offering a model to users, and after changing its endpoint, adapters, or the Pi/LiteLLM versions, the operator must verify both : Core / Pi: select the model, start a test session in a prepared test workspace, exercise an actual tool call and its returned result, a human review gate, and stop/resume. Check streaming, tool arguments, authentication, and reasoning/token-limit compatibility. A plain chat reply or tht pi test alone is not sufficient. Administration / LiteLLM: select the same model and generate descriptions for a small, non-sensitive test table. Check the structured result is accepted and the generation completes. Review the output quality before using it on real metadata. This action writes test metadata and may incur provider charges: use an authorized test database and approved data. There is no automatic certification flag or startup model probe. The operator owns this verification; do not infer compatibility from the model label or from success in just one path. Both adapters point to one catalog identity; Pi does not need to route through a new LiteLLM proxy. Models using only pi_auth cannot serve the current LiteLLM path and are excluded from shared selection. Session adapters \u00b6 Use pi_builtin for a model whose technical definition ships with Pi. This does not require pi_auth : a shared bundle credential lets native Pi and LiteLLM use the same provider identity: deepseek: authentication: mode: secret_env apiKeyEnv: DEEPSEEK_API_KEY session: mode: pi_builtin metadataGeneration: litellmProvider: deepseek models: deepseek-v4-pro: session: {} metadataGeneration: {} deepseek-v4-flash: session: {} metadataGeneration: {} Use openai_compatible for an explicit compatible endpoint. Each eligible session model must then declare the technical limits Pi needs. upstreamModel is optional and is used only when the endpoint expects a model name different from the catalog key. Provider integrations remain declarative. Do not register providers from harness/.pi/extensions/ ; those extensions implement the workflow and human gates only. Qwen 3.6 sessions and thinking controls \u00b6 For Qwen served through a vLLM-compatible chat template, declare the following inside the model's session block, alongside its context and output limits: reasoning: true compatibility: supportsDeveloperRole: false supportsReasoningEffort: false supportsStore: false maxTokensField: max_tokens thinkingFormat: qwen-chat-template This makes Pi send chat_template_kwargs.enable_thinking from the selected thinking level, with preserve_thinking: true . Choose off to explicitly disable thinking. The alternative thinkingFormat: qwen is for endpoints expecting top-level enable_thinking . Both formats require reasoning: true ; declaring reasoning: false does not tell the server to disable thinking. Omit thinkingFormat to preserve Pi's default behavior for other providers. Regenerate projections with the updated host CLI and recreate the local core container after rebuilding it. Do not add these fields directly to generated Pi files. These controls do not force tool calls or certify the workflow; perform the operator verification above. tht --installation /absolute/path/thothii-installation.yaml installation generate Use the model identifier exposed by your endpoint, such as qwen3.6-35b-a3b , and limits supported by that deployment. The thinking format configures the Pi session adapter; metadata generation continues to use its separate LiteLLM settings. If a session displays text such as {\"type\":\"bash\",\"command\":\"tht session show \u2026 --json\"} and never opens a review widget, that text is not an executed tool call. A verified cause was the Evidence JSON extension being loaded into interactive sessions and forcing response_format: {type: \"json_object\"} . Upgrade to the core image containing the fix: the extension belongs in .pi/evidence-extensions/ and is loaded explicitly only by Evidence authoring. It must not also remain in the automatically loaded .pi/extensions/ directory. Regenerating model configuration alone does not remove an extension from an old image. After upgrading, reload the browser and resume the session. Verify that Pi executes tht session show and opens a review widget. This fix does not require changing the Qwen server, forcing every turn to call a tool, or teaching the model to print tool-call JSON. Authentication \u00b6 Every provider chooses one explicit mode: secret_env names an approved key in the protected ThothII secret bundle through apiKeyEnv ; pi_auth uses Pi's protected authentication projection and is valid only for session-only pi_builtin providers; none is valid only with an explicit keyless endpoint. Secret values never belong in installation YAML, generated files, logs, CLI arguments, or browser requests. The YAML contains only an environment-variable name or an authentication mode. Pi's protected credential file remains selected by the installation authentication configuration. For catalog providers using secret_env , the bundle is authoritative in both Core and Admin. ThothII removes only the selected provider's old auth entry from the temporary Pi session snapshot; the operator's original Pi auth store and other providers are unchanged. Provider smoke checks use the same precedence, and model enumeration receives the catalog-declared bundle keys. A missing declared key is an error, not permission to fall back to Pi auth or the legacy generic key file. After rotating a bundle key, apply the normal installation lifecycle so processes reload it. The PSD descriptor now declares only deepseek/deepseek-v4-pro and deepseek/deepseek-v4-flash for both uses; it no longer duplicates them under deepseek-metadata . Historical records are not rewritten. A saved obsolete identity must be explicitly reselected from the current catalog; it is not silently remapped to another model or account. Generated runtime projections \u00b6 Before Compose starts, tht validates the installation and atomically writes deterministic files under deploy/<installation-id>/generated/ : generated/ \u251c\u2500\u2500 catalog.json \u251c\u2500\u2500 pi/ \u2502 \u251c\u2500\u2500 models.json \u2502 \u2514\u2500\u2500 settings.json \u2514\u2500\u2500 compose.models.yaml The normalized catalog is consumed by the backend. The Pi files and Compose override are boundary adapters. They are not configuration sources and are excluded from backup. Restore regenerates them from the installation descriptor. Run all lifecycle commands from the project root and select the descriptor explicitly when more than one installation exists: INSTALLATION=/absolute/path/deploy/example/thothii-installation.yaml tht --installation \"$INSTALLATION\" start tht --installation \"$INSTALLATION\" doctor After editing modelCatalog or provider credentials, apply the complete runtime projection with the normal installation lifecycle, then run the Pi checks: tht --installation \"$INSTALLATION\" start tht --installation \"$INSTALLATION\" pi doctor tht --installation \"$INSTALLATION\" pi test tht pi restart , tht pi update , and tht pi rollback refuse to run while generated model projections differ from modelCatalog : those commands recreate only core , so they must never partially apply an embedding change. tht pi update changes the Pi version; it is not the configuration command. There is no tht pi configure and no separate apply command. Migrating a legacy installation \u00b6 For schema-v2 descriptors with the former defaults.session and defaults.metadataGeneration , replace both with defaults.interaction . Equal legacy values are accepted and normalized in memory; the loader never rewrites the descriptor. Different values fail with migration_required : explicitly choose a model supporting both uses, remove both old fields, and set the single new field. Do not mix new and legacy fields. A Core-only legacy session default can be normalized when Admin AI is absent. The generated runtime catalog now uses schema version 2 and only defaultInteraction . Regenerate and apply all runtime projections with the matching host/backend release using the normal installation lifecycle; do not deploy only the backend against an old generated catalog or hand-edit generated JSON. The migrator reads the former installation metadataGeneration block and the two former Pi JSON files, but never modifies them. Supply the facts that cannot be inferred safely and write a separate candidate: tht --installation /absolute/path/legacy/thothii-installation.yaml installation migrate \\ --output /absolute/path/thothii-installation.v2.yaml \\ --session-default zai/glm-5.3 \\ --embedding-id ollama/qwen3-embedding:0.6b \\ --embedding-dimensions 1024 Review the candidate, move the legacy source files out of the installation only after approval, then select the v2 descriptor. Ambiguous aliases, endpoint conflicts, or missing authentication facts produce field-level errors; the migrator does not guess. The legacy CLI flag --session-default now supplies the unified interaction default in the candidate; if it conflicts with the legacy metadata default, align that choice explicitly before retrying. Troubleshooting \u00b6 Symptom Meaning Action migration_required A retired model source or installation schema is still present Run the installation migrator and review its candidate Invalid interaction default The canonical ID does not support all configured uses Correct defaults.interaction or the intended adapter blocks Generated projection drift Runtime files differ from the descriptor-derived bytes Run tht start or tht pi restart --yes --drain model_unavailable on create/resume The selected global model is no longer eligible Explicitly choose an eligible model; no fallback is applied Provider smoke failure Credentials, endpoint, or provider availability is invalid Correct the protected credential or catalog endpoint, restart, then run tht pi test","title":"Model configuration"},{"location":"general/pi-configuration/#installation-model-catalog","text":"ThothII has one operator-authored model source: modelCatalog in deploy/<installation-id>/thothii-installation.yaml . It declares models used by interactive Pi sessions, metadata generation, and the internal embedding service. Workspace descriptors never declare providers, model allowlists, defaults, embeddings, dimensions, or vector-store settings. Do not edit deploy/pi/models.json , deploy/pi/settings.json , files under generated/ , or provider/model environment defaults. Those former sources are retired.","title":"Installation Model Catalog"},{"location":"general/pi-configuration/#host-instructions-in-administration","text":"The Pi configuration navigation button opens Pi management . Its Host maintenance section selects the installation host's Linux, macOS, or Windows tab automatically; the browser's operating system does not affect it. Selecting another tab is still possible. The host CLI includes THT_HOST_PLATFORM in the generated Compose projection using the OS on which it runs. Generate projections on the destination host, not on another computer, and do not edit generated files. Without this projection (older deployments or native development), the backend reports its own OS; a Linux Docker container cannot discover whether the physical host is macOS or Windows. Run the updated host CLI's normal configuration reload on the destination installation to regenerate this information.","title":"Host instructions in Administration"},{"location":"general/pi-configuration/#minimal-catalog","text":"schemaVersion: 2 modelCatalog: defaults: interaction: zai/glm-5.3 embedding: id: ollama/qwen3-embedding:0.6b dimensions: 1024 providers: zai: endpoint: baseUrl: https://api.z.ai/api/coding/paas/v4 authentication: mode: secret_env apiKeyEnv: ZAI_API_KEY session: mode: openai_compatible metadataGeneration: litellmProvider: openai models: glm-5.3: label: GLM 5.3 session: reasoning: true contextWindow: 200000 maxTokens: 131072 metadataGeneration: {} Provider and model entries are maps. The keys form the canonical identity <provider-key>/<model-key> ; label is only display text. A model is eligible for a use only when it contains that use block: session makes it selectable for interactive sessions; metadataGeneration makes it selectable for description generation; embedding is a single installation-level model rather than a selectable list. defaults.interaction is the only LLM default, required once per installation, never per workspace. Core and Administration share the user's operational model choice. An explicit choice takes priority over the default and is remembered in this browser for the authenticated user and application mount. Switching workspace does not change the model. Browser-storage restrictions may limit remembering to the current visit; preferences do not synchronize across devices or change installation YAML. An unavailable remembered model is not silently replaced: select another configured model. When any metadata-generation models are configured, the default and the operational list must support both session and metadataGeneration . Entries for just one adapter may remain in the installation inventory, but are not selectable for global interaction. Core-only installations remain supported when no metadata-generation model is configured; Admin AI is then unavailable. The embedding model remains separate and is unaffected by the interaction selector. New sessions record the selected model in their manifest. Resume retains the session's workspace and revision, but uses the current global model (the installation default for clients that omit a model). Historical manifest model fields are not rewritten by resume. Archived/finalized sessions remain read-only.","title":"Minimal catalog"},{"location":"general/pi-configuration/#required-operator-verification-for-every-model","text":"Catalog validation checks configuration, not model behavior. Before offering a model to users, and after changing its endpoint, adapters, or the Pi/LiteLLM versions, the operator must verify both : Core / Pi: select the model, start a test session in a prepared test workspace, exercise an actual tool call and its returned result, a human review gate, and stop/resume. Check streaming, tool arguments, authentication, and reasoning/token-limit compatibility. A plain chat reply or tht pi test alone is not sufficient. Administration / LiteLLM: select the same model and generate descriptions for a small, non-sensitive test table. Check the structured result is accepted and the generation completes. Review the output quality before using it on real metadata. This action writes test metadata and may incur provider charges: use an authorized test database and approved data. There is no automatic certification flag or startup model probe. The operator owns this verification; do not infer compatibility from the model label or from success in just one path. Both adapters point to one catalog identity; Pi does not need to route through a new LiteLLM proxy. Models using only pi_auth cannot serve the current LiteLLM path and are excluded from shared selection.","title":"Required operator verification for every model"},{"location":"general/pi-configuration/#session-adapters","text":"Use pi_builtin for a model whose technical definition ships with Pi. This does not require pi_auth : a shared bundle credential lets native Pi and LiteLLM use the same provider identity: deepseek: authentication: mode: secret_env apiKeyEnv: DEEPSEEK_API_KEY session: mode: pi_builtin metadataGeneration: litellmProvider: deepseek models: deepseek-v4-pro: session: {} metadataGeneration: {} deepseek-v4-flash: session: {} metadataGeneration: {} Use openai_compatible for an explicit compatible endpoint. Each eligible session model must then declare the technical limits Pi needs. upstreamModel is optional and is used only when the endpoint expects a model name different from the catalog key. Provider integrations remain declarative. Do not register providers from harness/.pi/extensions/ ; those extensions implement the workflow and human gates only.","title":"Session adapters"},{"location":"general/pi-configuration/#qwen-36-sessions-and-thinking-controls","text":"For Qwen served through a vLLM-compatible chat template, declare the following inside the model's session block, alongside its context and output limits: reasoning: true compatibility: supportsDeveloperRole: false supportsReasoningEffort: false supportsStore: false maxTokensField: max_tokens thinkingFormat: qwen-chat-template This makes Pi send chat_template_kwargs.enable_thinking from the selected thinking level, with preserve_thinking: true . Choose off to explicitly disable thinking. The alternative thinkingFormat: qwen is for endpoints expecting top-level enable_thinking . Both formats require reasoning: true ; declaring reasoning: false does not tell the server to disable thinking. Omit thinkingFormat to preserve Pi's default behavior for other providers. Regenerate projections with the updated host CLI and recreate the local core container after rebuilding it. Do not add these fields directly to generated Pi files. These controls do not force tool calls or certify the workflow; perform the operator verification above. tht --installation /absolute/path/thothii-installation.yaml installation generate Use the model identifier exposed by your endpoint, such as qwen3.6-35b-a3b , and limits supported by that deployment. The thinking format configures the Pi session adapter; metadata generation continues to use its separate LiteLLM settings. If a session displays text such as {\"type\":\"bash\",\"command\":\"tht session show \u2026 --json\"} and never opens a review widget, that text is not an executed tool call. A verified cause was the Evidence JSON extension being loaded into interactive sessions and forcing response_format: {type: \"json_object\"} . Upgrade to the core image containing the fix: the extension belongs in .pi/evidence-extensions/ and is loaded explicitly only by Evidence authoring. It must not also remain in the automatically loaded .pi/extensions/ directory. Regenerating model configuration alone does not remove an extension from an old image. After upgrading, reload the browser and resume the session. Verify that Pi executes tht session show and opens a review widget. This fix does not require changing the Qwen server, forcing every turn to call a tool, or teaching the model to print tool-call JSON.","title":"Qwen 3.6 sessions and thinking controls"},{"location":"general/pi-configuration/#authentication","text":"Every provider chooses one explicit mode: secret_env names an approved key in the protected ThothII secret bundle through apiKeyEnv ; pi_auth uses Pi's protected authentication projection and is valid only for session-only pi_builtin providers; none is valid only with an explicit keyless endpoint. Secret values never belong in installation YAML, generated files, logs, CLI arguments, or browser requests. The YAML contains only an environment-variable name or an authentication mode. Pi's protected credential file remains selected by the installation authentication configuration. For catalog providers using secret_env , the bundle is authoritative in both Core and Admin. ThothII removes only the selected provider's old auth entry from the temporary Pi session snapshot; the operator's original Pi auth store and other providers are unchanged. Provider smoke checks use the same precedence, and model enumeration receives the catalog-declared bundle keys. A missing declared key is an error, not permission to fall back to Pi auth or the legacy generic key file. After rotating a bundle key, apply the normal installation lifecycle so processes reload it. The PSD descriptor now declares only deepseek/deepseek-v4-pro and deepseek/deepseek-v4-flash for both uses; it no longer duplicates them under deepseek-metadata . Historical records are not rewritten. A saved obsolete identity must be explicitly reselected from the current catalog; it is not silently remapped to another model or account.","title":"Authentication"},{"location":"general/pi-configuration/#generated-runtime-projections","text":"Before Compose starts, tht validates the installation and atomically writes deterministic files under deploy/<installation-id>/generated/ : generated/ \u251c\u2500\u2500 catalog.json \u251c\u2500\u2500 pi/ \u2502 \u251c\u2500\u2500 models.json \u2502 \u2514\u2500\u2500 settings.json \u2514\u2500\u2500 compose.models.yaml The normalized catalog is consumed by the backend. The Pi files and Compose override are boundary adapters. They are not configuration sources and are excluded from backup. Restore regenerates them from the installation descriptor. Run all lifecycle commands from the project root and select the descriptor explicitly when more than one installation exists: INSTALLATION=/absolute/path/deploy/example/thothii-installation.yaml tht --installation \"$INSTALLATION\" start tht --installation \"$INSTALLATION\" doctor After editing modelCatalog or provider credentials, apply the complete runtime projection with the normal installation lifecycle, then run the Pi checks: tht --installation \"$INSTALLATION\" start tht --installation \"$INSTALLATION\" pi doctor tht --installation \"$INSTALLATION\" pi test tht pi restart , tht pi update , and tht pi rollback refuse to run while generated model projections differ from modelCatalog : those commands recreate only core , so they must never partially apply an embedding change. tht pi update changes the Pi version; it is not the configuration command. There is no tht pi configure and no separate apply command.","title":"Generated runtime projections"},{"location":"general/pi-configuration/#migrating-a-legacy-installation","text":"For schema-v2 descriptors with the former defaults.session and defaults.metadataGeneration , replace both with defaults.interaction . Equal legacy values are accepted and normalized in memory; the loader never rewrites the descriptor. Different values fail with migration_required : explicitly choose a model supporting both uses, remove both old fields, and set the single new field. Do not mix new and legacy fields. A Core-only legacy session default can be normalized when Admin AI is absent. The generated runtime catalog now uses schema version 2 and only defaultInteraction . Regenerate and apply all runtime projections with the matching host/backend release using the normal installation lifecycle; do not deploy only the backend against an old generated catalog or hand-edit generated JSON. The migrator reads the former installation metadataGeneration block and the two former Pi JSON files, but never modifies them. Supply the facts that cannot be inferred safely and write a separate candidate: tht --installation /absolute/path/legacy/thothii-installation.yaml installation migrate \\ --output /absolute/path/thothii-installation.v2.yaml \\ --session-default zai/glm-5.3 \\ --embedding-id ollama/qwen3-embedding:0.6b \\ --embedding-dimensions 1024 Review the candidate, move the legacy source files out of the installation only after approval, then select the v2 descriptor. Ambiguous aliases, endpoint conflicts, or missing authentication facts produce field-level errors; the migrator does not guess. The legacy CLI flag --session-default now supplies the unified interaction default in the candidate; if it conflicts with the legacy metadata default, align that choice explicitly before retrying.","title":"Migrating a legacy installation"},{"location":"general/pi-configuration/#troubleshooting","text":"Symptom Meaning Action migration_required A retired model source or installation schema is still present Run the installation migrator and review its candidate Invalid interaction default The canonical ID does not support all configured uses Correct defaults.interaction or the intended adapter blocks Generated projection drift Runtime files differ from the descriptor-derived bytes Run tht start or tht pi restart --yes --drain model_unavailable on create/resume The selected global model is no longer eligible Explicitly choose an eligible model; no fallback is applied Provider smoke failure Credentials, endpoint, or provider availability is invalid Correct the protected credential or catalog endpoint, restart, then run tht pi test","title":"Troubleshooting"},{"location":"install/authentication-local/","text":"Local authentication \u00b6 Use local mode for a standalone PC or Mac, with shell.mode: full and shell.defaultLocale: en in the installation descriptor. Presentation and authentication are independent: selecting full does not create accounts. Omics embedded instead uses the upstream guide , not local users. Configure local authentication through tht ; passwords are entered at an echo-free prompt or read from a protected --password-file , never from a command argument. Bootstrap \u00b6 After the installation descriptor and protected secret bundle exist, configure the first enabled administrator: tht --installation /absolute/path/thothii-installation.yaml auth configure \\ --mode local --public-url http://127.0.0.1:8080 \\ --admin-user <operator-user> --admin-display-name <display-name> \\ --password-file /absolute/path/protected-password-file The password file is temporary operator input: keep it private and remove it after configuration. The resulting users.yaml contains Argon2id hashes, never plaintext passwords. To use prompts, omit the admin and password options in an interactive terminal. tht setup performs the same bootstrap before it starts the stack. The non-secret local auth.yaml has this exact shape: version: 1 mode: local publicUrl: http://127.0.0.1:8080 session: regularTtlSeconds: 43200 regularIdleSeconds: 7200 rememberTtlSeconds: 2592000 rememberIdleSeconds: 604800 oidcTtlSeconds: 28800 local: usersFile: users.yaml User administration \u00b6 tht auth user list [--json] tht auth user add <username> --role user|admin [--display-name <name>] [--password-file <file>] tht auth user set-password <username> [--password-file <file>] tht auth user enable <username> tht auth user disable <username> tht auth user grant <username> --role user|admin tht auth user revoke <username> --role user|admin tht auth user logout-all <username> --yes User commands are unavailable in OIDC mode. The last enabled administrator cannot be disabled or demoted. Every password, role, enabled-state, and logout-all change increments the user\u2019s authRevision , invalidating its sessions. tht auth status --json is redacted and suitable for machine use; JSON output is pristine on stdout. Session behavior and recovery \u00b6 Full shows its own login form and, after login, the verified display name in its header. The name menu contains Log out. This sends a CSRF-protected request to /api/auth/logout , revokes the session and returns to login. Language/theme preferences may remain in the browser; they are not credentials. An ordinary login expires after 2 hours idle or 12 hours absolute. Selecting Remember me makes the cookie persistent and changes the limits to 7 days idle or 30 days absolute. Remembered sessions survive a browser and backend restart, but not a user revision change, configuration revision change, logout, or restore. Restore does not include sessions or OIDC state and requires every user to authenticate again. If access is lost, use tht auth user set-password , enable , role changes, or logout-all as appropriate, then log in again. Do not copy passwords, hashes, cookies, CSRF values, or secret values into tickets, logs, or evidence. Check readiness with tht auth check ; add --json for the machine contract. Use tht doctor --json for the aggregate installation report. Projected server installations \u00b6 This section applies only when a Linux profile: server descriptor declares a runtime projection. The canonical authentication root stays root-owned and is the only authority. The container reads only the separate read-only runtime projection selected by CURRENT ; it never falls back to the canonical files or to a previous generation. Run projected mutations and repairs through the root-operated tht commands, and never edit runtime files directly. Mac, Windows, and local direct-file authentication remain unchanged when the projection is absent.","title":"Local authentication"},{"location":"install/authentication-local/#local-authentication","text":"Use local mode for a standalone PC or Mac, with shell.mode: full and shell.defaultLocale: en in the installation descriptor. Presentation and authentication are independent: selecting full does not create accounts. Omics embedded instead uses the upstream guide , not local users. Configure local authentication through tht ; passwords are entered at an echo-free prompt or read from a protected --password-file , never from a command argument.","title":"Local authentication"},{"location":"install/authentication-local/#bootstrap","text":"After the installation descriptor and protected secret bundle exist, configure the first enabled administrator: tht --installation /absolute/path/thothii-installation.yaml auth configure \\ --mode local --public-url http://127.0.0.1:8080 \\ --admin-user <operator-user> --admin-display-name <display-name> \\ --password-file /absolute/path/protected-password-file The password file is temporary operator input: keep it private and remove it after configuration. The resulting users.yaml contains Argon2id hashes, never plaintext passwords. To use prompts, omit the admin and password options in an interactive terminal. tht setup performs the same bootstrap before it starts the stack. The non-secret local auth.yaml has this exact shape: version: 1 mode: local publicUrl: http://127.0.0.1:8080 session: regularTtlSeconds: 43200 regularIdleSeconds: 7200 rememberTtlSeconds: 2592000 rememberIdleSeconds: 604800 oidcTtlSeconds: 28800 local: usersFile: users.yaml","title":"Bootstrap"},{"location":"install/authentication-local/#user-administration","text":"tht auth user list [--json] tht auth user add <username> --role user|admin [--display-name <name>] [--password-file <file>] tht auth user set-password <username> [--password-file <file>] tht auth user enable <username> tht auth user disable <username> tht auth user grant <username> --role user|admin tht auth user revoke <username> --role user|admin tht auth user logout-all <username> --yes User commands are unavailable in OIDC mode. The last enabled administrator cannot be disabled or demoted. Every password, role, enabled-state, and logout-all change increments the user\u2019s authRevision , invalidating its sessions. tht auth status --json is redacted and suitable for machine use; JSON output is pristine on stdout.","title":"User administration"},{"location":"install/authentication-local/#session-behavior-and-recovery","text":"Full shows its own login form and, after login, the verified display name in its header. The name menu contains Log out. This sends a CSRF-protected request to /api/auth/logout , revokes the session and returns to login. Language/theme preferences may remain in the browser; they are not credentials. An ordinary login expires after 2 hours idle or 12 hours absolute. Selecting Remember me makes the cookie persistent and changes the limits to 7 days idle or 30 days absolute. Remembered sessions survive a browser and backend restart, but not a user revision change, configuration revision change, logout, or restore. Restore does not include sessions or OIDC state and requires every user to authenticate again. If access is lost, use tht auth user set-password , enable , role changes, or logout-all as appropriate, then log in again. Do not copy passwords, hashes, cookies, CSRF values, or secret values into tickets, logs, or evidence. Check readiness with tht auth check ; add --json for the machine contract. Use tht doctor --json for the aggregate installation report.","title":"Session behavior and recovery"},{"location":"install/authentication-local/#projected-server-installations","text":"This section applies only when a Linux profile: server descriptor declares a runtime projection. The canonical authentication root stays root-owned and is the only authority. The container reads only the separate read-only runtime projection selected by CURRENT ; it never falls back to the canonical files or to a previous generation. Run projected mutations and repairs through the root-operated tht commands, and never edit runtime files directly. Mac, Windows, and local direct-file authentication remain unchanged when the projection is absent.","title":"Projected server installations"},{"location":"install/authentication-oidc/","text":"Generic OIDC authentication \u00b6 Use this guide for ThothII's own login , normally shell.mode: full on an autonomous server. It is not the integration procedure for an already logged-in Omics user. That deployment uses embedded/upstream , even when Omics's identity provider is Authentik. OIDC mode supports a standards-based provider. The browser flow is generic: Authorization Code, PKCE S256, state, nonce, issuer/signature/audience/expiry validation, and the fixed callback <publicUrl>/api/auth/oidc/callback . The browser and API must use the same origin; configure the reverse proxy to preserve that public origin and callback path. publicUrl is the public origin, without an application subpath. The current full OIDC browser entry and callback use /api/auth/oidc/login and /api/auth/oidc/callback ; arbitrary prefixed OIDC hosting is not implemented by selecting a different backendBaseUrl . Configure the installation with tht : tht auth configure --mode oidc --public-url <https-public-origin> \\ --issuer <https-issuer> --client-id <client-id> \\ --authentik-base-url <https-provider-origin> \\ --user-group 'TOT Users' --admin-group 'TOT Admin' The OIDC client secret is supplied through the protected secret bundle under the exact key THT_OIDC_CLIENT_SECRET ; it is never written into auth.yaml . The default scopes are exactly openid , profile , and email . Keep AUTH_MODE unset when using this file. A simultaneously mounted local/OIDC configuration and AUTH_MODE=upstream is an error, not a fallback chain. The non-secret OIDC configuration has this exact shape (replace angle-bracket placeholders with operator values): version: 1 mode: oidc publicUrl: <https-public-origin> session: regularTtlSeconds: 43200 regularIdleSeconds: 7200 rememberTtlSeconds: 2592000 rememberIdleSeconds: 604800 oidcTtlSeconds: 28800 oidc: issuer: <https-issuer> clientId: <client-id> clientSecretRef: THT_OIDC_CLIENT_SECRET scopes: [openid, profile, email] groupsClaim: groups groupCatalog: driver: authentik baseUrl: <https-provider-origin> apiTokenRef: THT_AUTHENTIK_API_TOKEN authorization: groupRoles: TOT Users: [user] TOT Admin: [admin] The groups claim is mandatory \u00b6 The ID token must contain a direct, non-empty groups array of strings. ThothII does not follow distributed claims, overage links, or indirect provider expansion. Missing or malformed claims fail closed. A browser callback exposes only HTTP 401 oidc_callback_failed ; it never reveals whether the claim was missing, malformed, indirect, or overage-style. The redacted diagnostic and interactive device-flow contract uses oidc_groups_claim_invalid for invalid group-claim or device-flow identity results. Configured group names are exact and case-sensitive. The union of matched mappings determines the Thoth roles. A token with no mapped group is authenticated but has no role and cannot use protected routes. Additional provider groups are ignored silently, without an error or warning. Group existence is separately proven by the configured catalog adapter; this is why a generic OIDC provider may authenticate while still failing installation readiness. Checks and diagnostics \u00b6 The surfaces have distinct semantics and this order is recommended: Workspace Validate performs static authentication validation without contacting the provider. tht auth check performs live, non-interactive authentication diagnosis, including discovery, issuer/JWKS, catalog credentials, and all configured mapped groups. tht auth check --interactive repeats live diagnosis and additionally validates a device-flow identity and its direct groups claim when Device Authorization is available. Installation diagnostics perform aggregate live workspace and authentication validation. The live CLI forms are: tht auth check tht auth check --json For a provider that advertises Device Authorization, tht auth check --interactive presents a verification URI and one-time user code on the terminal, waits for completion, and validates a real ID token including groups . It is an operator check, not a replacement for browser login. tht doctor emits this exact ordered report: descriptor , files , docker , compose , configuration , authentication , services , core-http , frontend-http , workspace-registry , workflow , pi . Its authentication entry is live and non-interactive. Any authentication failure prevents activation according to the static or live scope of the relevant diagnostic surface. The complete closed diagnostic-code union and exact role-to-permission expansion are in the authentication architecture . Browser login and logout \u00b6 ThothII redirects the browser to the provider and creates its own opaque session after validating the callback. An existing provider SSO session may avoid another password prompt, but this remains a distinct ThothII login/session, unlike Omics upstream. Full's name menu logs out of ThothII only. It does not revoke the provider session or log out other applications, so a subsequent login can return immediately through SSO. No provider token is placed in the UI adapter or browser storage. See the manual acceptance matrix .","title":"OIDC authentication"},{"location":"install/authentication-oidc/#generic-oidc-authentication","text":"Use this guide for ThothII's own login , normally shell.mode: full on an autonomous server. It is not the integration procedure for an already logged-in Omics user. That deployment uses embedded/upstream , even when Omics's identity provider is Authentik. OIDC mode supports a standards-based provider. The browser flow is generic: Authorization Code, PKCE S256, state, nonce, issuer/signature/audience/expiry validation, and the fixed callback <publicUrl>/api/auth/oidc/callback . The browser and API must use the same origin; configure the reverse proxy to preserve that public origin and callback path. publicUrl is the public origin, without an application subpath. The current full OIDC browser entry and callback use /api/auth/oidc/login and /api/auth/oidc/callback ; arbitrary prefixed OIDC hosting is not implemented by selecting a different backendBaseUrl . Configure the installation with tht : tht auth configure --mode oidc --public-url <https-public-origin> \\ --issuer <https-issuer> --client-id <client-id> \\ --authentik-base-url <https-provider-origin> \\ --user-group 'TOT Users' --admin-group 'TOT Admin' The OIDC client secret is supplied through the protected secret bundle under the exact key THT_OIDC_CLIENT_SECRET ; it is never written into auth.yaml . The default scopes are exactly openid , profile , and email . Keep AUTH_MODE unset when using this file. A simultaneously mounted local/OIDC configuration and AUTH_MODE=upstream is an error, not a fallback chain. The non-secret OIDC configuration has this exact shape (replace angle-bracket placeholders with operator values): version: 1 mode: oidc publicUrl: <https-public-origin> session: regularTtlSeconds: 43200 regularIdleSeconds: 7200 rememberTtlSeconds: 2592000 rememberIdleSeconds: 604800 oidcTtlSeconds: 28800 oidc: issuer: <https-issuer> clientId: <client-id> clientSecretRef: THT_OIDC_CLIENT_SECRET scopes: [openid, profile, email] groupsClaim: groups groupCatalog: driver: authentik baseUrl: <https-provider-origin> apiTokenRef: THT_AUTHENTIK_API_TOKEN authorization: groupRoles: TOT Users: [user] TOT Admin: [admin]","title":"Generic OIDC authentication"},{"location":"install/authentication-oidc/#the-groups-claim-is-mandatory","text":"The ID token must contain a direct, non-empty groups array of strings. ThothII does not follow distributed claims, overage links, or indirect provider expansion. Missing or malformed claims fail closed. A browser callback exposes only HTTP 401 oidc_callback_failed ; it never reveals whether the claim was missing, malformed, indirect, or overage-style. The redacted diagnostic and interactive device-flow contract uses oidc_groups_claim_invalid for invalid group-claim or device-flow identity results. Configured group names are exact and case-sensitive. The union of matched mappings determines the Thoth roles. A token with no mapped group is authenticated but has no role and cannot use protected routes. Additional provider groups are ignored silently, without an error or warning. Group existence is separately proven by the configured catalog adapter; this is why a generic OIDC provider may authenticate while still failing installation readiness.","title":"The groups claim is mandatory"},{"location":"install/authentication-oidc/#checks-and-diagnostics","text":"The surfaces have distinct semantics and this order is recommended: Workspace Validate performs static authentication validation without contacting the provider. tht auth check performs live, non-interactive authentication diagnosis, including discovery, issuer/JWKS, catalog credentials, and all configured mapped groups. tht auth check --interactive repeats live diagnosis and additionally validates a device-flow identity and its direct groups claim when Device Authorization is available. Installation diagnostics perform aggregate live workspace and authentication validation. The live CLI forms are: tht auth check tht auth check --json For a provider that advertises Device Authorization, tht auth check --interactive presents a verification URI and one-time user code on the terminal, waits for completion, and validates a real ID token including groups . It is an operator check, not a replacement for browser login. tht doctor emits this exact ordered report: descriptor , files , docker , compose , configuration , authentication , services , core-http , frontend-http , workspace-registry , workflow , pi . Its authentication entry is live and non-interactive. Any authentication failure prevents activation according to the static or live scope of the relevant diagnostic surface. The complete closed diagnostic-code union and exact role-to-permission expansion are in the authentication architecture .","title":"Checks and diagnostics"},{"location":"install/authentication-oidc/#browser-login-and-logout","text":"ThothII redirects the browser to the provider and creates its own opaque session after validating the callback. An existing provider SSO session may avoid another password prompt, but this remains a distinct ThothII login/session, unlike Omics upstream. Full's name menu logs out of ThothII only. It does not revoke the provider session or log out other applications, so a subsequent login can return immediately through SSO. No provider token is placed in the UI adapter or browser storage. See the manual acceptance matrix .","title":"Browser login and logout"},{"location":"install/authentik/","text":"Authentik provider configuration \u00b6 For full with direct OIDC , ThothII uses generic OIDC in the browser. Authentik provides the identity provider and group catalog without adding a proprietary flow. The provider/client/group setup below applies to that case only. For embedded in Omics , retain Omics's existing Authentik authentication and configure ThothII as upstream. Omics verifies datamart_builder.access and administrator status and the proxy supplies the identity; no additional ThothII OIDC client, login or local user is required for that path. Follow the portal integration guide . sequenceDiagram participant Browser participant ThothII participant Authentik Browser->>ThothII: Sign in ThothII->>Authentik: Authorization Code with PKCE Authentik-->>Browser: Login and consent Browser->>ThothII: Callback with code ThothII->>Authentik: Token exchange Authentik-->>ThothII: Identity and groups ThothII-->>Browser: Opaque session OIDC provider \u00b6 Create an OAuth2/OIDC application and provider. Register exactly PUBLIC_URL/api/auth/oidc/callback . Enable the openid , profile , and email scopes. Configure a direct groups claim as an array of strings. Group catalog \u00b6 Create a dedicated service account with read-only access to groups. Store its token in the protected bundle as THT_AUTHENTIK_API_TOKEN . Map the exact enterprise group names to the ThothII user and admin roles in auth.yaml . Unmapped groups are ignored. A configured group that does not exist produces a closed error. Diagnostics \u00b6 tht auth check checks discovery, the issuer, JWKS, catalog access, and the configured groups. The --interactive option also verifies identity through device flow when the provider supports it. Rotate the OIDC secret and group-catalog token separately. Neither may appear in YAML, shell history, logs, or diagnostic output.","title":"Authentik"},{"location":"install/authentik/#authentik-provider-configuration","text":"For full with direct OIDC , ThothII uses generic OIDC in the browser. Authentik provides the identity provider and group catalog without adding a proprietary flow. The provider/client/group setup below applies to that case only. For embedded in Omics , retain Omics's existing Authentik authentication and configure ThothII as upstream. Omics verifies datamart_builder.access and administrator status and the proxy supplies the identity; no additional ThothII OIDC client, login or local user is required for that path. Follow the portal integration guide . sequenceDiagram participant Browser participant ThothII participant Authentik Browser->>ThothII: Sign in ThothII->>Authentik: Authorization Code with PKCE Authentik-->>Browser: Login and consent Browser->>ThothII: Callback with code ThothII->>Authentik: Token exchange Authentik-->>ThothII: Identity and groups ThothII-->>Browser: Opaque session","title":"Authentik provider configuration"},{"location":"install/authentik/#oidc-provider","text":"Create an OAuth2/OIDC application and provider. Register exactly PUBLIC_URL/api/auth/oidc/callback . Enable the openid , profile , and email scopes. Configure a direct groups claim as an array of strings.","title":"OIDC provider"},{"location":"install/authentik/#group-catalog","text":"Create a dedicated service account with read-only access to groups. Store its token in the protected bundle as THT_AUTHENTIK_API_TOKEN . Map the exact enterprise group names to the ThothII user and admin roles in auth.yaml . Unmapped groups are ignored. A configured group that does not exist produces a closed error.","title":"Group catalog"},{"location":"install/authentik/#diagnostics","text":"tht auth check checks discovery, the issuer, JWKS, catalog access, and the configured groups. The --interactive option also verifies identity through device flow when the provider supports it. Rotate the OIDC secret and group-catalog token separately. Neither may appear in YAML, shell history, logs, or diagnostic output.","title":"Diagnostics"},{"location":"install/dwh-auth-client-enrollment/","text":"DWH REST client enrollment \u00b6 The dwh-auth credential belongs to one ThothII installation and is needed only when the workspace uses the rest_api transport. Trasporto Materiale richiesto rest_api URL HTTPS, API_KEY_FILE , eventuale TLS_CA_FILE postgres_direct Credenziali PostgreSQL e configurazione TLS PostgreSQL ssh_tunnel Credenziali PostgreSQL e materiale SSH Delivery and storage \u00b6 Receive the key and CA through separate protected channels. Store the key in the installation vault or in a regular file accessible only to the authorized account. Do not put it in Git, YAML files, arguments, logs, or shared screens. ACME Limited configuration \u00b6 Esempio di binding headless per il workspace acme-ebikes : THT_WS_ACME_EBIKES_DWH_TRANSPORT=rest_api THT_WS_ACME_EBIKES_DWH_BASE_URL=https://dwh.acme.example/dwh/ THT_WS_ACME_EBIKES_DWH_API_KEY_FILE=/run/secrets/acme-ebikes-dwh-api-key THT_WS_ACME_EBIKES_DWH_TLS_CA_FILE=/run/secrets/acme-ebikes-dwh-ca.pem The workspace suffix comes from the immutable ID, with hyphens changed to underscores and letters converted to uppercase. API_KEY_FILE contains the mounted file path, not the key value. Rotation and revocation \u00b6 During rotation, receive the new generation, update the vault or mounted file, and confirm connectivity through the harmless /rpc/ping route. The server owner revokes the previous generation only after this confirmation. A 401 means the key is missing, unknown, expired, or revoked. A 503 means the authorization service or registry is unavailable. In either case, do not bypass REST or weaken TLS verification.","title":"Client enrollment"},{"location":"install/dwh-auth-client-enrollment/#dwh-rest-client-enrollment","text":"The dwh-auth credential belongs to one ThothII installation and is needed only when the workspace uses the rest_api transport. Trasporto Materiale richiesto rest_api URL HTTPS, API_KEY_FILE , eventuale TLS_CA_FILE postgres_direct Credenziali PostgreSQL e configurazione TLS PostgreSQL ssh_tunnel Credenziali PostgreSQL e materiale SSH","title":"DWH REST client enrollment"},{"location":"install/dwh-auth-client-enrollment/#delivery-and-storage","text":"Receive the key and CA through separate protected channels. Store the key in the installation vault or in a regular file accessible only to the authorized account. Do not put it in Git, YAML files, arguments, logs, or shared screens.","title":"Delivery and storage"},{"location":"install/dwh-auth-client-enrollment/#acme-limited-configuration","text":"Esempio di binding headless per il workspace acme-ebikes : THT_WS_ACME_EBIKES_DWH_TRANSPORT=rest_api THT_WS_ACME_EBIKES_DWH_BASE_URL=https://dwh.acme.example/dwh/ THT_WS_ACME_EBIKES_DWH_API_KEY_FILE=/run/secrets/acme-ebikes-dwh-api-key THT_WS_ACME_EBIKES_DWH_TLS_CA_FILE=/run/secrets/acme-ebikes-dwh-ca.pem The workspace suffix comes from the immutable ID, with hyphens changed to underscores and letters converted to uppercase. API_KEY_FILE contains the mounted file path, not the key value.","title":"ACME Limited configuration"},{"location":"install/dwh-auth-client-enrollment/#rotation-and-revocation","text":"During rotation, receive the new generation, update the vault or mounted file, and confirm connectivity through the harmless /rpc/ping route. The server owner revokes the previous generation only after this confirmation. A 401 means the key is missing, unknown, expired, or revoked. A 503 means the authorization service or registry is unavailable. In either case, do not bypass REST or weaken TLS verification.","title":"Rotation and revocation"},{"location":"install/dwh-auth-server/","text":"dwh-auth : server guide \u00b6 dwh-auth protects the REST /dwh/ route with a separate key for each ThothII installation. It runs as a separate Linux service, does not read DWH data, and does not connect directly to PostgreSQL. flowchart LR CLIENT[\"Installazione ThothII\"] -->|\"X-API-Key\"| NGINX[\"Nginx\"] NGINX --> AUTH[\"dwh-auth\\nUnix socket\"] AUTH --> REGISTRY[\"Registro chiavi\\nactive e revoked\"] AUTH -->|\"authorized\"| REST[\"DWH REST\"] Security boundaries \u00b6 A key identifies an installation, not a person. Keys and backups stay in protected files and never enter Git, logs, arguments, or public JSON. The registry stores digests and metadata, never the key in plaintext. The REST route must be exposed only through verified TLS. Installation \u00b6 Il servizio usa questi percorsi: Oggetto Percorso Binario /usr/local/sbin/dwh-auth Unit systemd /etc/systemd/system/dwh-auth.service Registro /var/lib/dwh-auth/ Socket /run/dwh-auth/verify.sock Consegne protette /root/dwh-auth-provision/ Install the binary and unit with root ownership, create the dwh-auth service user, and enable the unit with systemctl enable --now dwh-auth . The socket must be accessible to Nginx's group. Creating and revoking keys \u00b6 Esempio per l'installazione ACME Limited: sudo dwh-auth --registry-root /var/lib/dwh-auth key create \\ --installation-id acme-factory-primary \\ --description acme-factory-primary \\ --output /root/dwh-auth-provision/acme-factory-primary.key Deliver the file through an enterprise vault or an authenticated channel. To rotate a key, create a new one, distribute it, update the client, and revoke the old one using its public ID: sudo dwh-auth --registry-root /var/lib/dwh-auth key revoke \\ --key-id PUBLIC_KEY_ID \\ --reason scheduled-rotation Revocation is permanent. Keep encrypted registry backups before every mutation. Nginx integration \u00b6 Nginx forwards the key to the dwh-auth socket. Only an authorized response allows the request to reach DWH REST. Missing, unknown, expired, or revoked keys receive 401 ; an unavailable service or registry produces 503 .","title":"Server"},{"location":"install/dwh-auth-server/#dwh-auth-server-guide","text":"dwh-auth protects the REST /dwh/ route with a separate key for each ThothII installation. It runs as a separate Linux service, does not read DWH data, and does not connect directly to PostgreSQL. flowchart LR CLIENT[\"Installazione ThothII\"] -->|\"X-API-Key\"| NGINX[\"Nginx\"] NGINX --> AUTH[\"dwh-auth\\nUnix socket\"] AUTH --> REGISTRY[\"Registro chiavi\\nactive e revoked\"] AUTH -->|\"authorized\"| REST[\"DWH REST\"]","title":"dwh-auth: server guide"},{"location":"install/dwh-auth-server/#security-boundaries","text":"A key identifies an installation, not a person. Keys and backups stay in protected files and never enter Git, logs, arguments, or public JSON. The registry stores digests and metadata, never the key in plaintext. The REST route must be exposed only through verified TLS.","title":"Security boundaries"},{"location":"install/dwh-auth-server/#installation","text":"Il servizio usa questi percorsi: Oggetto Percorso Binario /usr/local/sbin/dwh-auth Unit systemd /etc/systemd/system/dwh-auth.service Registro /var/lib/dwh-auth/ Socket /run/dwh-auth/verify.sock Consegne protette /root/dwh-auth-provision/ Install the binary and unit with root ownership, create the dwh-auth service user, and enable the unit with systemctl enable --now dwh-auth . The socket must be accessible to Nginx's group.","title":"Installation"},{"location":"install/dwh-auth-server/#creating-and-revoking-keys","text":"Esempio per l'installazione ACME Limited: sudo dwh-auth --registry-root /var/lib/dwh-auth key create \\ --installation-id acme-factory-primary \\ --description acme-factory-primary \\ --output /root/dwh-auth-provision/acme-factory-primary.key Deliver the file through an enterprise vault or an authenticated channel. To rotate a key, create a new one, distribute it, update the client, and revoke the old one using its public ID: sudo dwh-auth --registry-root /var/lib/dwh-auth key revoke \\ --key-id PUBLIC_KEY_ID \\ --reason scheduled-rotation Revocation is permanent. Keep encrypted registry backups before every mutation.","title":"Creating and revoking keys"},{"location":"install/dwh-auth-server/#nginx-integration","text":"Nginx forwards the key to the dwh-auth socket. Only an authorized response allows the request to reach DWH REST. Missing, unknown, expired, or revoked keys receive 401 ; an unavailable service or registry produces 503 .","title":"Nginx integration"},{"location":"install/dwh-auth-tls/","text":"TLS for DWH REST \u00b6 The DWH key may be used only over verified TLS. Authorization or availability errors never justify disabling certificate verification. Private CA \u00b6 When DWH REST uses an enterprise CA, deliver the certificate separately from the API key. The CA is not a credential, but its integrity is part of the security boundary. Keep it out of Git and make it unwritable by unauthorized users. Esempio ACME Limited: THT_WS_ACME_EBIKES_DWH_TLS_CA_FILE=/run/secrets/acme-ebikes-dwh-ca.pem Out-of-band fingerprint \u00b6 Calculate the fingerprint of the received file and compare it through an independent channel: openssl x509 -noout -fingerprint -sha256 \\ -in /absolute/protected/acme-ebikes-dwh-ca.pem The certificate SAN must include the exact name used by the binding, such as dwh.acme.example . Renewal \u00b6 Prepare the new certificate and chain. Confirm the SAN and fingerprint out of band. Distribute the new CA to clients while temporarily keeping the old one. Update the binding and confirm connectivity with normal TLS. Install the server certificate. Remove the old trust after the agreed window. Do not use curl -k , disable TLS, or embed complete certificates or fingerprints in shared documents.","title":"TLS"},{"location":"install/dwh-auth-tls/#tls-for-dwh-rest","text":"The DWH key may be used only over verified TLS. Authorization or availability errors never justify disabling certificate verification.","title":"TLS for DWH REST"},{"location":"install/dwh-auth-tls/#private-ca","text":"When DWH REST uses an enterprise CA, deliver the certificate separately from the API key. The CA is not a credential, but its integrity is part of the security boundary. Keep it out of Git and make it unwritable by unauthorized users. Esempio ACME Limited: THT_WS_ACME_EBIKES_DWH_TLS_CA_FILE=/run/secrets/acme-ebikes-dwh-ca.pem","title":"Private CA"},{"location":"install/dwh-auth-tls/#out-of-band-fingerprint","text":"Calculate the fingerprint of the received file and compare it through an independent channel: openssl x509 -noout -fingerprint -sha256 \\ -in /absolute/protected/acme-ebikes-dwh-ca.pem The certificate SAN must include the exact name used by the binding, such as dwh.acme.example .","title":"Out-of-band fingerprint"},{"location":"install/dwh-auth-tls/#renewal","text":"Prepare the new certificate and chain. Confirm the SAN and fingerprint out of band. Distribute the new CA to clients while temporarily keeping the old one. Update the binding and confirm connectivity with normal TLS. Install the server certificate. Remove the old trust after the agreed window. Do not use curl -k , disable TLS, or embed complete certificates or fingerprints in shared documents.","title":"Renewal"},{"location":"install/first-start/","text":"Install and first start \u00b6 Use one complete procedure for a fresh installation: Italian manual installation English manual installation 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. What must be ready \u00b6 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. 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. Secrets, certificates, Pi authentication and endpoint bindings are protected local files. Do not commit them or copy the configuration of another machine unchanged. Follow the ordered procedure \u00b6 The bilingual guides provide the exact commands for: Cloning the selected revision and checking prerequisites. Bootstrapping the native host command. Preparing catalog passwords and using tht setup --profile local --shell-mode full --shell-default-locale en --configure-only . Completing model, authentication and workspace credentials. Generating configuration, building images and explicitly running catalog-migrate . 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. For an already configured installation: tht --installation /absolute/path/thothii-installation.yaml status tht --installation /absolute/path/thothii-installation.yaml doctor --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. After startup \u00b6 Prepare workspaces , configure a database in Database Management , and complete the functional checks in the installation guide before using real data. See display mode and language , local authentication , OIDC and model configuration for later changes. Embedded portal integration is separate from a fresh standalone setup. 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.","title":"Start here"},{"location":"install/first-start/#install-and-first-start","text":"Use one complete procedure for a fresh installation: Italian manual installation English manual installation 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.","title":"Install and first start"},{"location":"install/first-start/#what-must-be-ready","text":"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. 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. Secrets, certificates, Pi authentication and endpoint bindings are protected local files. Do not commit them or copy the configuration of another machine unchanged.","title":"What must be ready"},{"location":"install/first-start/#follow-the-ordered-procedure","text":"The bilingual guides provide the exact commands for: Cloning the selected revision and checking prerequisites. Bootstrapping the native host command. Preparing catalog passwords and using tht setup --profile local --shell-mode full --shell-default-locale en --configure-only . Completing model, authentication and workspace credentials. Generating configuration, building images and explicitly running catalog-migrate . 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. For an already configured installation: tht --installation /absolute/path/thothii-installation.yaml status tht --installation /absolute/path/thothii-installation.yaml doctor --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.","title":"Follow the ordered procedure"},{"location":"install/first-start/#after-startup","text":"Prepare workspaces , configure a database in Database Management , and complete the functional checks in the installation guide before using real data. See display mode and language , local authentication , OIDC and model configuration for later changes. Embedded portal integration is separate from a fresh standalone setup. 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.","title":"After startup"},{"location":"install/shell-and-language/","text":"Display mode and language \u00b6 ThothII can run with its own application header ( full ) or inside an integrated portal ( embedded ). Display mode and authentication are separate choices. Installation Display Authentication Standalone local instance full Local ThothII account Standalone server full Local accounts or configured OIDC provider Integrated portal embedded Identity verified by the portal's trusted server proxy Standalone setup \u00b6 Follow the complete Italian or English installation procedure. It explicitly selects --shell-mode full --shell-default-locale en and separates configuration, credentials, initial migrations and startup. Do not skip those steps by running setup alone. The authored installation descriptor contains: shell: mode: full defaultLocale: en Use it for an Italian initial interface. Existing browser language preferences can override that initial value. Full mode remembers language and theme in the browser. For an existing installation, preserve the current descriptor and edit only the intended settings; do not rerun setup to overwrite it. With a current host tht binary: tht --installation /absolute/path/thothii-installation.yaml installation generate tht --installation /absolute/path/thothii-installation.yaml start tht --installation /absolute/path/thothii-installation.yaml status tht --installation /absolute/path/thothii-installation.yaml doctor --json Generation updates derived configuration; it does not start services. start applies the installation's normal lifecycle and is not guaranteed to touch only the frontend. Follow the deployment's maintenance procedure and retain its network, authentication and model settings. Do not edit generated files or remove persistent volumes. Authentication and embedded deployments \u00b6 Full mode does not configure login by itself. See local authentication or OIDC , with Authentik as a provider option. Embedded mode requires a compatible portal integration, not just a descriptor toggle. The portal owns login/logout and supplies a server-verified identity. A presentation adapter does not authenticate users. The core must not be reachable by a route that bypasses the trusted proxy. Do not add a second OIDC login to an already authenticated upstream deployment. Portal implementation details belong to the developer integration reference in the repository , not to the standalone installation procedure. Three different languages \u00b6 Interface language controls labels, forms and application messages. Session interaction language is captured when a session is created. Resuming it retains that language even if the interface language changes later. Workspace language concerns domain content and retrieval; switching the interface does not translate Evidence, SQL, identifiers or database values. In embedded mode the interface follows the portal's language and theme. A portal language change may reload the page. Saved session artifacts remain available, but resuming work is explicit; a reload does not by itself request a new model generation.","title":"Display mode and language"},{"location":"install/shell-and-language/#display-mode-and-language","text":"ThothII can run with its own application header ( full ) or inside an integrated portal ( embedded ). Display mode and authentication are separate choices. Installation Display Authentication Standalone local instance full Local ThothII account Standalone server full Local accounts or configured OIDC provider Integrated portal embedded Identity verified by the portal's trusted server proxy","title":"Display mode and language"},{"location":"install/shell-and-language/#standalone-setup","text":"Follow the complete Italian or English installation procedure. It explicitly selects --shell-mode full --shell-default-locale en and separates configuration, credentials, initial migrations and startup. Do not skip those steps by running setup alone. The authored installation descriptor contains: shell: mode: full defaultLocale: en Use it for an Italian initial interface. Existing browser language preferences can override that initial value. Full mode remembers language and theme in the browser. For an existing installation, preserve the current descriptor and edit only the intended settings; do not rerun setup to overwrite it. With a current host tht binary: tht --installation /absolute/path/thothii-installation.yaml installation generate tht --installation /absolute/path/thothii-installation.yaml start tht --installation /absolute/path/thothii-installation.yaml status tht --installation /absolute/path/thothii-installation.yaml doctor --json Generation updates derived configuration; it does not start services. start applies the installation's normal lifecycle and is not guaranteed to touch only the frontend. Follow the deployment's maintenance procedure and retain its network, authentication and model settings. Do not edit generated files or remove persistent volumes.","title":"Standalone setup"},{"location":"install/shell-and-language/#authentication-and-embedded-deployments","text":"Full mode does not configure login by itself. See local authentication or OIDC , with Authentik as a provider option. Embedded mode requires a compatible portal integration, not just a descriptor toggle. The portal owns login/logout and supplies a server-verified identity. A presentation adapter does not authenticate users. The core must not be reachable by a route that bypasses the trusted proxy. Do not add a second OIDC login to an already authenticated upstream deployment. Portal implementation details belong to the developer integration reference in the repository , not to the standalone installation procedure.","title":"Authentication and embedded deployments"},{"location":"install/shell-and-language/#three-different-languages","text":"Interface language controls labels, forms and application messages. Session interaction language is captured when a session is created. Resuming it retains that language even if the interface language changes later. Workspace language concerns domain content and retrieval; switching the interface does not translate Evidence, SQL, identifiers or database values. In embedded mode the interface follows the portal's language and theme. A portal language change may reload the page. Saved session artifacts remain available, but resuming work is explicit; a reload does not by itself request a new model generation.","title":"Three different languages"},{"location":"install/standalone-manual-en/","text":"Manual standalone installation \u00b6 Versione italiana This is the verification procedure for preparing THothII as a standalone application in full mode on macOS, Windows, and Linux. In this document, \u201cstandalone\u201d means that the user does not need to install Node.js, Python or Pi on the host: the application services and local semantic services run through Docker. DWH and LLM providers remain external endpoints configured by the installation; this is not an offline package. This path uses no graphical installer, native launcher, or Docker Hub image. It starts from a Gitea clone and uses explicit terminal commands. Publishing pre-built images is a later step. Verification matrix \u00b6 System Recommended terminal Runtime Test architecture macOS supported by the installed Docker Desktop version Bash in Terminal Docker Desktop Apple Silicon ( arm64 ) Windows 11 Ubuntu inside WSL2 Docker Desktop with WSL2 integration x64 ( amd64 ) Ubuntu Linux 22.04 or 24.04 Bash Docker Engine + Compose v2 x64 ( amd64 ) Intel macOS is excluded from the first verification campaign. ARM Linux may be tested when the machine\u2019s Docker runtime reports arm64 , but it is not part of the minimum matrix. Documentation and Mac prerequisite checks have passed. Complete fresh installations on all three systems remain pending; this matrix describes the tests to perform, not completed certification. Before you start \u00b6 You need: access to the THothII Gitea repository and the workspace Git repository; Git; Docker Desktop on macOS and Windows, or Docker Engine with the Compose v2 plugin on Linux; Bash, curl , OpenSSL and shasum (Ubuntu package: libdigest-sha-perl ); enough disk space to build the images and download the embedding model; the DWH and LLM endpoints, plus the credentials required by the installation. On Linux, the current user must be able to run Docker. If the system requires sudo , add the user to the Docker group according to local policy and open a new session before continuing. On Windows, run every command in this guide from Ubuntu under WSL2. In Docker Desktop, enable WSL2 integration for that distribution. Clone the project inside the WSL2 Linux filesystem, for example under ~/src , rather than under /mnt/c : this avoids slow builds and path/line-ending issues. Pi does not need to be installed on the host. Check the runtime before or immediately after cloning: docker version docker compose version docker version --format '{{.Server.Arch}}' The last command must return amd64 , x86_64 , arm64 , or aarch64 . 1. Clone a project revision \u00b6 Use the project repository on Gitea: 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: 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 \u00b6 From the clone root: bash scripts/check-standalone-prerequisites.sh export PATH=\"$HOME/.local/bin:$PATH\" THT_INSTALL_DIRECTORY=\"$HOME/.local/bin\" bash scripts/install-tht.sh tht version install-tht.sh bootstraps only the native tht operator command; it does not install a desktop version of THothII. It uses the repository\u2019s Docker builder, installs the binary for the current terminal environment, and installs it in the user directory. Persist $HOME/.local/bin in your shell PATH for new terminals too. An existing tht in this directory will be updated. On Windows, run these commands inside WSL2. The installed tht binary is the Linux binary inside WSL2; the application runtime remains Docker Desktop. Do not use scripts/install-tht.ps1 as the primary path for this test. 3. Configure and start the local installation \u00b6 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: umask 077 mkdir -p deploy/local/secrets for name in catalog-runtime-password catalog-migrator-password; do target=\"deploy/local/secrets/$name\" if [ ! -e \"$target\" ]; then (set -C; openssl rand -hex 32 > \"$target\") || exit 1 fi done export THT_CATALOG_RUNTIME_PASSWORD_SOURCE=\"$(pwd -P)/deploy/local/secrets/catalog-runtime-password\" export THT_CATALOG_MIGRATOR_PASSWORD_SOURCE=\"$(pwd -P)/deploy/local/secrets/catalog-migrator-password\" Do not regenerate passwords for an initialized catalog. Configure without starting services: tht setup --profile local --shell-mode full --shell-default-locale en --configure-only Answer the prompts as follows: Prompt Value or rule Installation ID local , unless one clone hosts multiple installations Deployment profile local DWH API endpoint An http(s) URL without user, password, query, or fragment; may be empty for a smoke-only test LLM API endpoint An http(s) URL without credentials; may be empty for a smoke-only test Workspace repository URL The workspace repository URL, not the THothII source clone Workspace branch Normally main Workspace access ssh with a deploy key, or https with a protected credential file File paths Accept the default paths under deploy/local/secrets/ for the first test Secret templates Answer yes when protected files do not exist yet Authentication Configure the local login required by the installation; never put passwords on a command line The generated configuration is local and ignored by Git: deploy/local/thothii-installation.yaml deploy/local/operator.env deploy/local/auth/ deploy/local/secrets/ Edit secrets only in protected local files; never commit them. deploy/env/local.env.example is a tracked reference; the generated path deploy/local/operator.env is the active path for this installation. Complete protected files \u00b6 If setup created blank templates, enter the values with a local editor: chmod 600 deploy/local/secrets/* \"${EDITOR:-vi}\" deploy/local/secrets/thothii.secrets The bundle must contain only KEY=VALUE lines for credentials actually used by modelCatalog . The allowed names and credential boundary are documented in the local file deploy/secrets/README.md . Do not put tokens in URLs, the YAML descriptor, the Git repository, or commands copied into the shell. For SSH workspace access, also provide the private key and known_hosts file requested by setup. For HTTPS access, provide the Git credential file and any required CA. Both must remain protected and outside version control. Before starting, complete these additional configuration steps: 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. 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 and the local example deploy/psd/thothii-installation.yaml.example . 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. Complete the workspace Git files. SSH requires an authorized deploy key and verified known-hosts; HTTPS requires the credential file and CA bundle expected by the overlay. Blank templates cannot provide repository access. After editing generated configuration, do not rerun setup: it rejects different existing content. Generate the projections and run the explicit migration below. Use THT_GIT_ACCESS=https if that was selected during setup. This block targets the fresh local descriptor with only the Git overlay; custom installations must include their extra descriptor overlays in the same order. INSTALLATION=\"$(pwd -P)/deploy/local/thothii-installation.yaml\" tht --installation \"$INSTALLATION\" installation generate THT_PROJECT=\"thothii-$(printf '%s' \"$INSTALLATION\" | shasum -a 256 | cut -c 1-12)\" THT_GIT_ACCESS=ssh compose=( docker compose --project-name \"$THT_PROJECT\" --project-directory \"$(pwd -P)\" --env-file \"$(pwd -P)/deploy/local/operator.env\" -f compose.yaml -f deploy/compose.local.yaml -f \"deploy/compose.git-$THT_GIT_ACCESS.yaml\" -f deploy/local/generated/compose.models.yaml ) \"${compose[@]}\" config --quiet \"${compose[@]}\" build core frontend \"${compose[@]}\" up -d catalog-db \"${compose[@]}\" run --rm catalog-migrate tht --installation \"$INSTALLATION\" start Stop if a command fails. The project name matches the hash used by tht , preserving volume identity. catalog-migrate applies Catalog and Memory migrations; tht start does not run it automatically. Initial embedding-model download may take time. Use this installation-specific sequence, not run-stack.sh with a different environment/project name. 4. Verify the installation \u00b6 The descriptor generated for the default ID is: INSTALLATION=\"$(pwd -P)/deploy/local/thothii-installation.yaml\" test -f \"$INSTALLATION\" bash scripts/verify-standalone-install.sh \"$INSTALLATION\" The verifier is read-only: it runs tht doctor --json and tht status without restarting the stack, regenerating configuration, or printing secret contents. Gate A \u2014 platform smoke test on all three computers \u00b6 Record the following for each machine: 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: curl --fail --silent --show-error http://127.0.0.1:8080/health Gate B \u2014 functional verification \u00b6 Run this on at least one machine with available endpoints and credentials: First follow Workspace operations 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. open http://127.0.0.1:8080 ; sign in with the configured local account; verify that the configured workspace is readable; start a real question and complete the review gates through final SQL; 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 \u00b6 Use the explicit descriptor when more than one installation may be discoverable: INSTALLATION=\"$PWD/deploy/local/thothii-installation.yaml\" tht --installation \"$INSTALLATION\" status tht --installation \"$INSTALLATION\" start tht --installation \"$INSTALLATION\" start --build tht --installation \"$INSTALLATION\" logs tht --installation \"$INSTALLATION\" doctor --json tht --installation \"$INSTALLATION\" stop Use start --build after source changes or to rebuild images from the current checkout. stop preserves volumes, sessions, the catalog, Pi state, Qdrant data, and the embedding model. Do not use docker compose down --volumes during a normal test: it is destructive and removes local data. For upgrades requiring migrations, follow the release runbook before starting the new application. Quick diagnosis \u00b6 Symptom Check Docker Engine is not reachable start Docker Desktop or the Docker service and rerun docker info Windows sees Docker but Bash fails run the guide inside Ubuntu WSL2 and enable that distribution in Docker Desktop tht: command not found open a new shell and check command -v tht ; rerun the bootstrap if needed line-ending or executable-script errors use a clone in the WSL2/Linux filesystem and rerun bash scripts/... unsupported architecture check docker version --format '{{.Server.Arch}}' ; the test requires amd64 or arm64 missing descriptor or env file use deploy/local/... generated by tht setup , not an arbitrary copied file healthy stack but workflow failure check external URLs, the credential bundle, workspace Git, and authentication separately data appears missing check that down --volumes was not used; stop does not remove volumes Acceptance checklist \u00b6 [ ] 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 \u00b6 The following remain future work: publishing pre-built images on Docker Hub; reducing prompts through a dedicated non-interactive configuration; creating DMG, MSI/EXE, AppImage, or other native installers; providing an offline runtime or bundling a local DWH/LLM into the application. Related documents \u00b6 Install and first start Shell and localization Workspace operations deploy/secrets/README.md (runtime secrets)","title":"Mac, Windows, Linux \u2014 English"},{"location":"install/standalone-manual-en/#manual-standalone-installation","text":"Versione italiana This is the verification procedure for preparing THothII as a standalone application in full mode on macOS, Windows, and Linux. In this document, \u201cstandalone\u201d means that the user does not need to install Node.js, Python or Pi on the host: the application services and local semantic services run through Docker. DWH and LLM providers remain external endpoints configured by the installation; this is not an offline package. This path uses no graphical installer, native launcher, or Docker Hub image. It starts from a Gitea clone and uses explicit terminal commands. Publishing pre-built images is a later step.","title":"Manual standalone installation"},{"location":"install/standalone-manual-en/#verification-matrix","text":"System Recommended terminal Runtime Test architecture macOS supported by the installed Docker Desktop version Bash in Terminal Docker Desktop Apple Silicon ( arm64 ) Windows 11 Ubuntu inside WSL2 Docker Desktop with WSL2 integration x64 ( amd64 ) Ubuntu Linux 22.04 or 24.04 Bash Docker Engine + Compose v2 x64 ( amd64 ) Intel macOS is excluded from the first verification campaign. ARM Linux may be tested when the machine\u2019s Docker runtime reports arm64 , but it is not part of the minimum matrix. Documentation and Mac prerequisite checks have passed. Complete fresh installations on all three systems remain pending; this matrix describes the tests to perform, not completed certification.","title":"Verification matrix"},{"location":"install/standalone-manual-en/#before-you-start","text":"You need: access to the THothII Gitea repository and the workspace Git repository; Git; Docker Desktop on macOS and Windows, or Docker Engine with the Compose v2 plugin on Linux; Bash, curl , OpenSSL and shasum (Ubuntu package: libdigest-sha-perl ); enough disk space to build the images and download the embedding model; the DWH and LLM endpoints, plus the credentials required by the installation. On Linux, the current user must be able to run Docker. If the system requires sudo , add the user to the Docker group according to local policy and open a new session before continuing. On Windows, run every command in this guide from Ubuntu under WSL2. In Docker Desktop, enable WSL2 integration for that distribution. Clone the project inside the WSL2 Linux filesystem, for example under ~/src , rather than under /mnt/c : this avoids slow builds and path/line-ending issues. Pi does not need to be installed on the host. Check the runtime before or immediately after cloning: docker version docker compose version docker version --format '{{.Server.Arch}}' The last command must return amd64 , x86_64 , arm64 , or aarch64 .","title":"Before you start"},{"location":"install/standalone-manual-en/#1-clone-a-project-revision","text":"Use the project repository on Gitea: 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: 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.","title":"1. Clone a project revision"},{"location":"install/standalone-manual-en/#2-check-prerequisites-and-install-the-operator-command","text":"From the clone root: bash scripts/check-standalone-prerequisites.sh export PATH=\"$HOME/.local/bin:$PATH\" THT_INSTALL_DIRECTORY=\"$HOME/.local/bin\" bash scripts/install-tht.sh tht version install-tht.sh bootstraps only the native tht operator command; it does not install a desktop version of THothII. It uses the repository\u2019s Docker builder, installs the binary for the current terminal environment, and installs it in the user directory. Persist $HOME/.local/bin in your shell PATH for new terminals too. An existing tht in this directory will be updated. On Windows, run these commands inside WSL2. The installed tht binary is the Linux binary inside WSL2; the application runtime remains Docker Desktop. Do not use scripts/install-tht.ps1 as the primary path for this test.","title":"2. Check prerequisites and install the operator command"},{"location":"install/standalone-manual-en/#3-configure-and-start-the-local-installation","text":"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: umask 077 mkdir -p deploy/local/secrets for name in catalog-runtime-password catalog-migrator-password; do target=\"deploy/local/secrets/$name\" if [ ! -e \"$target\" ]; then (set -C; openssl rand -hex 32 > \"$target\") || exit 1 fi done export THT_CATALOG_RUNTIME_PASSWORD_SOURCE=\"$(pwd -P)/deploy/local/secrets/catalog-runtime-password\" export THT_CATALOG_MIGRATOR_PASSWORD_SOURCE=\"$(pwd -P)/deploy/local/secrets/catalog-migrator-password\" Do not regenerate passwords for an initialized catalog. Configure without starting services: tht setup --profile local --shell-mode full --shell-default-locale en --configure-only Answer the prompts as follows: Prompt Value or rule Installation ID local , unless one clone hosts multiple installations Deployment profile local DWH API endpoint An http(s) URL without user, password, query, or fragment; may be empty for a smoke-only test LLM API endpoint An http(s) URL without credentials; may be empty for a smoke-only test Workspace repository URL The workspace repository URL, not the THothII source clone Workspace branch Normally main Workspace access ssh with a deploy key, or https with a protected credential file File paths Accept the default paths under deploy/local/secrets/ for the first test Secret templates Answer yes when protected files do not exist yet Authentication Configure the local login required by the installation; never put passwords on a command line The generated configuration is local and ignored by Git: deploy/local/thothii-installation.yaml deploy/local/operator.env deploy/local/auth/ deploy/local/secrets/ Edit secrets only in protected local files; never commit them. deploy/env/local.env.example is a tracked reference; the generated path deploy/local/operator.env is the active path for this installation.","title":"3. Configure and start the local installation"},{"location":"install/standalone-manual-en/#complete-protected-files","text":"If setup created blank templates, enter the values with a local editor: chmod 600 deploy/local/secrets/* \"${EDITOR:-vi}\" deploy/local/secrets/thothii.secrets The bundle must contain only KEY=VALUE lines for credentials actually used by modelCatalog . The allowed names and credential boundary are documented in the local file deploy/secrets/README.md . Do not put tokens in URLs, the YAML descriptor, the Git repository, or commands copied into the shell. For SSH workspace access, also provide the private key and known_hosts file requested by setup. For HTTPS access, provide the Git credential file and any required CA. Both must remain protected and outside version control. Before starting, complete these additional configuration steps: 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. 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 and the local example deploy/psd/thothii-installation.yaml.example . 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. Complete the workspace Git files. SSH requires an authorized deploy key and verified known-hosts; HTTPS requires the credential file and CA bundle expected by the overlay. Blank templates cannot provide repository access. After editing generated configuration, do not rerun setup: it rejects different existing content. Generate the projections and run the explicit migration below. Use THT_GIT_ACCESS=https if that was selected during setup. This block targets the fresh local descriptor with only the Git overlay; custom installations must include their extra descriptor overlays in the same order. INSTALLATION=\"$(pwd -P)/deploy/local/thothii-installation.yaml\" tht --installation \"$INSTALLATION\" installation generate THT_PROJECT=\"thothii-$(printf '%s' \"$INSTALLATION\" | shasum -a 256 | cut -c 1-12)\" THT_GIT_ACCESS=ssh compose=( docker compose --project-name \"$THT_PROJECT\" --project-directory \"$(pwd -P)\" --env-file \"$(pwd -P)/deploy/local/operator.env\" -f compose.yaml -f deploy/compose.local.yaml -f \"deploy/compose.git-$THT_GIT_ACCESS.yaml\" -f deploy/local/generated/compose.models.yaml ) \"${compose[@]}\" config --quiet \"${compose[@]}\" build core frontend \"${compose[@]}\" up -d catalog-db \"${compose[@]}\" run --rm catalog-migrate tht --installation \"$INSTALLATION\" start Stop if a command fails. The project name matches the hash used by tht , preserving volume identity. catalog-migrate applies Catalog and Memory migrations; tht start does not run it automatically. Initial embedding-model download may take time. Use this installation-specific sequence, not run-stack.sh with a different environment/project name.","title":"Complete protected files"},{"location":"install/standalone-manual-en/#4-verify-the-installation","text":"The descriptor generated for the default ID is: INSTALLATION=\"$(pwd -P)/deploy/local/thothii-installation.yaml\" test -f \"$INSTALLATION\" bash scripts/verify-standalone-install.sh \"$INSTALLATION\" The verifier is read-only: it runs tht doctor --json and tht status without restarting the stack, regenerating configuration, or printing secret contents.","title":"4. Verify the installation"},{"location":"install/standalone-manual-en/#gate-a-platform-smoke-test-on-all-three-computers","text":"Record the following for each machine: 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: curl --fail --silent --show-error http://127.0.0.1:8080/health","title":"Gate A \u2014 platform smoke test on all three computers"},{"location":"install/standalone-manual-en/#gate-b-functional-verification","text":"Run this on at least one machine with available endpoints and credentials: First follow Workspace operations 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. open http://127.0.0.1:8080 ; sign in with the configured local account; verify that the configured workspace is readable; start a real question and complete the review gates through final SQL; 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.","title":"Gate B \u2014 functional verification"},{"location":"install/standalone-manual-en/#daily-lifecycle","text":"Use the explicit descriptor when more than one installation may be discoverable: INSTALLATION=\"$PWD/deploy/local/thothii-installation.yaml\" tht --installation \"$INSTALLATION\" status tht --installation \"$INSTALLATION\" start tht --installation \"$INSTALLATION\" start --build tht --installation \"$INSTALLATION\" logs tht --installation \"$INSTALLATION\" doctor --json tht --installation \"$INSTALLATION\" stop Use start --build after source changes or to rebuild images from the current checkout. stop preserves volumes, sessions, the catalog, Pi state, Qdrant data, and the embedding model. Do not use docker compose down --volumes during a normal test: it is destructive and removes local data. For upgrades requiring migrations, follow the release runbook before starting the new application.","title":"Daily lifecycle"},{"location":"install/standalone-manual-en/#quick-diagnosis","text":"Symptom Check Docker Engine is not reachable start Docker Desktop or the Docker service and rerun docker info Windows sees Docker but Bash fails run the guide inside Ubuntu WSL2 and enable that distribution in Docker Desktop tht: command not found open a new shell and check command -v tht ; rerun the bootstrap if needed line-ending or executable-script errors use a clone in the WSL2/Linux filesystem and rerun bash scripts/... unsupported architecture check docker version --format '{{.Server.Arch}}' ; the test requires amd64 or arm64 missing descriptor or env file use deploy/local/... generated by tht setup , not an arbitrary copied file healthy stack but workflow failure check external URLs, the credential bundle, workspace Git, and authentication separately data appears missing check that down --volumes was not used; stop does not remove volumes","title":"Quick diagnosis"},{"location":"install/standalone-manual-en/#acceptance-checklist","text":"[ ] 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.","title":"Acceptance checklist"},{"location":"install/standalone-manual-en/#out-of-scope-for-this-release","text":"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.","title":"Out of scope for this release"},{"location":"install/standalone-manual-en/#related-documents","text":"Install and first start Shell and localization Workspace operations deploy/secrets/README.md (runtime secrets)","title":"Related documents"},{"location":"install/standalone-manual-it/","text":"Installazione manuale standalone \u00b6 English version Questa \u00e8 la procedura di prova per predisporre THothII come applicazione autonoma in modalit\u00e0 full su macOS, Windows e Linux. In questo documento \u201cautonoma\u201d significa che l\u2019utente 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\u2019installazione; questa procedura non \u00e8 un pacchetto offline. Il percorso non usa installer grafici, launcher nativi o immagini Docker Hub. Si parte da un clone Gitea e si usano comandi espliciti da terminale. La pubblicazione di immagini pre-costruite \u00e8 una fase successiva. Matrice di verifica \u00b6 Sistema Terminale raccomandato Runtime Architettura della prova macOS supportato dalla versione Docker Desktop installata Bash nel Terminale Docker Desktop Apple Silicon ( arm64 ) Windows 11 Ubuntu dentro WSL2 Docker Desktop con integrazione WSL2 x64 ( amd64 ) Linux Ubuntu 22.04 o 24.04 Bash Docker Engine + Compose v2 x64 ( amd64 ) Intel macOS non fa parte della prima campagna di verifica. ARM Linux pu\u00f2 essere provato quando il runtime Docker della macchina restituisce arm64 , ma non \u00e8 un requisito della matrice minima. Le verifiche documentali e dei prerequisiti Mac sono passate. Le installazioni complete da zero sui tre sistemi restano da eseguire: la matrice indica le prove previste, non una certificazione. Cosa serve prima di iniziare \u00b6 Servono: accesso al repository Gitea di THothII e al repository Git dei workspace; Git; Docker Desktop su macOS e Windows, oppure Docker Engine con il plugin Compose v2 su Linux; Bash, curl , OpenSSL e shasum (su Ubuntu, pacchetto libdigest-sha-perl ); spazio disco sufficiente per compilare le immagini e scaricare il modello di embedding; gli endpoint DWH e LLM, pi\u00f9 le credenziali che l\u2019installazione deve usare. Su Linux l\u2019utente corrente deve poter eseguire Docker. Se il sistema richiede sudo , aggiungere l\u2019utente al gruppo Docker secondo la policy locale e aprire una nuova sessione prima di continuare. Su Windows usare Ubuntu in WSL2 per tutti i comandi di questa guida. In Docker Desktop attivare l\u2019integrazione 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 \u00e8 necessario installare Pi sull\u2019host. Verificare il runtime prima del clone o subito dopo: docker version docker compose version docker version --format '{{.Server.Arch}}' L\u2019ultima istruzione deve restituire amd64 , x86_64 , arm64 o aarch64 . 1. Clonare una revisione del progetto \u00b6 Usare il repository di progetto su Gitea: 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 \u00e8 gi\u00e0 autorizzata su Gitea: git clone git@git.tylconsulting.it:mptyl/ThothII.git Per una prova ripetibile annotare l\u2019hash stampato da git rev-parse . In una campagna successiva usare la revisione/tag approvata dal maintainer invece di seguire implicitamente una main che pu\u00f2 cambiare. 2. Verificare i prerequisiti e installare il comando operatore \u00b6 Dal root del clone: bash scripts/check-standalone-prerequisites.sh export PATH=\"$HOME/.local/bin:$PATH\" THT_INSTALL_DIRECTORY=\"$HOME/.local/bin\" bash scripts/install-tht.sh tht version install-tht.sh \u00e8 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\u2019ambiente del terminale e lo installa nella directory utente. Aggiungere $HOME/.local/bin al PATH della shell anche per i terminali successivi. Un tht gi\u00e0 presente in quella directory viene aggiornato. Su Windows, eseguire questi comandi dentro WSL2. Il binario tht installato \u00e8 quello Linux di WSL2; il runtime dell\u2019applicazione rimane Docker Desktop. Non usare scripts/install-tht.ps1 come percorso principale di questa prova. 3. Configurare e avviare l\u2019installazione locale \u00b6 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\u00e0 esistenti: umask 077 mkdir -p deploy/local/secrets for name in catalog-runtime-password catalog-migrator-password; do target=\"deploy/local/secrets/$name\" if [ ! -e \"$target\" ]; then (set -C; openssl rand -hex 32 > \"$target\") || exit 1 fi done export THT_CATALOG_RUNTIME_PASSWORD_SOURCE=\"$(pwd -P)/deploy/local/secrets/catalog-runtime-password\" export THT_CATALOG_MIGRATOR_PASSWORD_SOURCE=\"$(pwd -P)/deploy/local/secrets/catalog-migrator-password\" Non rigenerare le password di un catalogo gi\u00e0 inizializzato. Configurare senza avviare i servizi: tht setup --profile local --shell-mode full --shell-default-locale en --configure-only Rispondere ai prompt nel seguente modo: Prompt Valore o regola Installation ID local , salvo necessit\u00e0 di pi\u00f9 installazioni nello stesso clone Deployment profile local DWH API endpoint URL http(s) senza user, password, query o fragment; pu\u00f2 restare vuoto per il solo smoke test LLM API endpoint URL http(s) senza credenziali; pu\u00f2 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\u2019installazione; non inserire password in una riga di comando La configurazione generata \u00e8 locale e ignorata da Git: deploy/local/thothii-installation.yaml deploy/local/operator.env deploy/local/auth/ deploy/local/secrets/ Modificare i segreti solo nei file locali protetti; non committarli. Il file deploy/env/local.env.example \u00e8 un riferimento tracciato; il percorso generato da tht setup , deploy/local/operator.env , \u00e8 quello da usare per questa installazione. Completare i file protetti \u00b6 Se il setup ha creato template vuoti, inserire i valori con un editor locale: chmod 600 deploy/local/secrets/* \"${EDITOR:-vi}\" deploy/local/secrets/thothii.secrets Il bundle deve contenere solo righe KEY=VALUE per le credenziali effettivamente usate dal modelCatalog . I nomi ammessi e il confine delle credenziali sono descritti nel file locale deploy/secrets/README.md . Non mettere token nelle URL, nel descriptor YAML, nel repository Git o nei comandi copiati nella shell. Per accesso workspace SSH, predisporre anche la chiave privata e il file known_hosts indicati dal setup. Per accesso HTTPS, predisporre il credential file Git e l\u2019eventuale CA. Entrambi devono restare protetti e fuori dal controllo versione. Prima dell'avvio completare anche questi passaggi: 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. Sostituire il modelCatalog generico nel descriptor con la configurazione provider/modelli approvata. I default generati non replicano il Mac esistente. Vedere configurazione Pi/modelli e l'esempio locale deploy/psd/thothii-installation.yaml.example . 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. Completare i file Git del workspace. SSH richiede una chiave deploy autorizzata e known-hosts verificato; HTTPS richiede il credential file e il bundle CA previsti dall'overlay. I template vuoti non consentono l'accesso al repository. Dopo aver modificato la configurazione generata, non rilanciare setup: rifiuta file esistenti con contenuti diversi. Generare le proiezioni ed eseguire la migrazione esplicita indicata sotto. Impostare THT_GIT_ACCESS=https se scelto nel setup. Il blocco usa il nuovo descriptor local con il solo overlay Git; per installazioni personalizzate includere gli overlay aggiuntivi nello stesso ordine del descriptor. INSTALLATION=\"$(pwd -P)/deploy/local/thothii-installation.yaml\" tht --installation \"$INSTALLATION\" installation generate THT_PROJECT=\"thothii-$(printf '%s' \"$INSTALLATION\" | shasum -a 256 | cut -c 1-12)\" THT_GIT_ACCESS=ssh compose=( docker compose --project-name \"$THT_PROJECT\" --project-directory \"$(pwd -P)\" --env-file \"$(pwd -P)/deploy/local/operator.env\" -f compose.yaml -f deploy/compose.local.yaml -f \"deploy/compose.git-$THT_GIT_ACCESS.yaml\" -f deploy/local/generated/compose.models.yaml ) \"${compose[@]}\" config --quiet \"${compose[@]}\" build core frontend \"${compose[@]}\" up -d catalog-db \"${compose[@]}\" run --rm catalog-migrate tht --installation \"$INSTALLATION\" start Fermarsi se un comando fallisce. Il nome progetto coincide con l'hash usato da tht , preservando l'identit\u00e0 dei volumi. catalog-migrate applica le migrazioni Catalog e Memory; tht start non lo esegue automaticamente. Il primo download del modello embedding pu\u00f2 richiedere tempo. Usare questa sequenza legata all'installazione, non run-stack.sh con env/progetto diversi. 4. Verificare l\u2019installazione \u00b6 Il descriptor generato per l\u2019ID predefinito \u00e8: INSTALLATION=\"$(pwd -P)/deploy/local/thothii-installation.yaml\" test -f \"$INSTALLATION\" bash scripts/verify-standalone-install.sh \"$INSTALLATION\" Il verificatore \u00e8 read-only: esegue tht doctor --json e tht status , senza ristartare lo stack, rigenerare la configurazione o stampare il contenuto dei segreti. Gate A \u2014 smoke di piattaforma, su tutti e tre i computer \u00b6 Registrare per ogni macchina: 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 \u00e8 integro, Docker e Compose sono raggiungibili, tht doctor \u00e8 OK, lo stack \u00e8 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\u00e0 HTTP con: curl --fail --silent --show-error http://127.0.0.1:8080/health Gate B \u2014 verifica funzionale \u00b6 Eseguire almeno su una macchina con endpoint e credenziali disponibili: Seguire prima Workspace operations 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. aprire http://127.0.0.1:8080 ; autenticarsi con l\u2019account locale configurato; verificare che il workspace configurato sia leggibile; avviare una domanda reale e completare i gate di revisione fino alla SQL finale; fermare e riavviare l\u2019installazione, 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\u00e0 Docker: registrare separatamente l\u2019endpoint o il componente fallito. Ciclo di vita quotidiano \u00b6 Usare il descriptor esplicito quando pi\u00f9 installazioni possono essere scoperte: INSTALLATION=\"$PWD/deploy/local/thothii-installation.yaml\" tht --installation \"$INSTALLATION\" status tht --installation \"$INSTALLATION\" start tht --installation \"$INSTALLATION\" start --build tht --installation \"$INSTALLATION\" logs tht --installation \"$INSTALLATION\" doctor --json tht --installation \"$INSTALLATION\" stop start --build \u00e8 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: \u00e8 un\u2019operazione distruttiva che cancella i dati locali. Per aggiornamenti che richiedono migrazioni, seguire il runbook della release prima dell'avvio. Diagnosi rapida \u00b6 Sintomo Controllo Docker Engine is not reachable avviare Docker Desktop oppure il servizio Docker e ripetere docker info Windows vede Docker ma Bash fallisce eseguire la guida dentro Ubuntu WSL2 e abilitare l\u2019integrazione 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 \u00b6 [ ] Il clone proviene dal repository Gitea atteso e la revisione \u00e8 stata annotata. [ ] Docker Desktop/Engine e Compose v2 sono disponibili. [ ] Il runtime restituisce un\u2019architettura ammessa. [ ] tht \u00e8 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 \u00b6 Restano attivit\u00e0 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\u2019applicazione. Documenti collegati \u00b6 Install and first start Shell and localization Workspace operations deploy/secrets/README.md (runtime secrets)","title":"Mac, Windows, Linux \u2014 Italiano"},{"location":"install/standalone-manual-it/#installazione-manuale-standalone","text":"English version Questa \u00e8 la procedura di prova per predisporre THothII come applicazione autonoma in modalit\u00e0 full su macOS, Windows e Linux. In questo documento \u201cautonoma\u201d significa che l\u2019utente 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\u2019installazione; questa procedura non \u00e8 un pacchetto offline. Il percorso non usa installer grafici, launcher nativi o immagini Docker Hub. Si parte da un clone Gitea e si usano comandi espliciti da terminale. La pubblicazione di immagini pre-costruite \u00e8 una fase successiva.","title":"Installazione manuale standalone"},{"location":"install/standalone-manual-it/#matrice-di-verifica","text":"Sistema Terminale raccomandato Runtime Architettura della prova macOS supportato dalla versione Docker Desktop installata Bash nel Terminale Docker Desktop Apple Silicon ( arm64 ) Windows 11 Ubuntu dentro WSL2 Docker Desktop con integrazione WSL2 x64 ( amd64 ) Linux Ubuntu 22.04 o 24.04 Bash Docker Engine + Compose v2 x64 ( amd64 ) Intel macOS non fa parte della prima campagna di verifica. ARM Linux pu\u00f2 essere provato quando il runtime Docker della macchina restituisce arm64 , ma non \u00e8 un requisito della matrice minima. Le verifiche documentali e dei prerequisiti Mac sono passate. Le installazioni complete da zero sui tre sistemi restano da eseguire: la matrice indica le prove previste, non una certificazione.","title":"Matrice di verifica"},{"location":"install/standalone-manual-it/#cosa-serve-prima-di-iniziare","text":"Servono: accesso al repository Gitea di THothII e al repository Git dei workspace; Git; Docker Desktop su macOS e Windows, oppure Docker Engine con il plugin Compose v2 su Linux; Bash, curl , OpenSSL e shasum (su Ubuntu, pacchetto libdigest-sha-perl ); spazio disco sufficiente per compilare le immagini e scaricare il modello di embedding; gli endpoint DWH e LLM, pi\u00f9 le credenziali che l\u2019installazione deve usare. Su Linux l\u2019utente corrente deve poter eseguire Docker. Se il sistema richiede sudo , aggiungere l\u2019utente al gruppo Docker secondo la policy locale e aprire una nuova sessione prima di continuare. Su Windows usare Ubuntu in WSL2 per tutti i comandi di questa guida. In Docker Desktop attivare l\u2019integrazione 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 \u00e8 necessario installare Pi sull\u2019host. Verificare il runtime prima del clone o subito dopo: docker version docker compose version docker version --format '{{.Server.Arch}}' L\u2019ultima istruzione deve restituire amd64 , x86_64 , arm64 o aarch64 .","title":"Cosa serve prima di iniziare"},{"location":"install/standalone-manual-it/#1-clonare-una-revisione-del-progetto","text":"Usare il repository di progetto su Gitea: 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 \u00e8 gi\u00e0 autorizzata su Gitea: git clone git@git.tylconsulting.it:mptyl/ThothII.git Per una prova ripetibile annotare l\u2019hash stampato da git rev-parse . In una campagna successiva usare la revisione/tag approvata dal maintainer invece di seguire implicitamente una main che pu\u00f2 cambiare.","title":"1. Clonare una revisione del progetto"},{"location":"install/standalone-manual-it/#2-verificare-i-prerequisiti-e-installare-il-comando-operatore","text":"Dal root del clone: bash scripts/check-standalone-prerequisites.sh export PATH=\"$HOME/.local/bin:$PATH\" THT_INSTALL_DIRECTORY=\"$HOME/.local/bin\" bash scripts/install-tht.sh tht version install-tht.sh \u00e8 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\u2019ambiente del terminale e lo installa nella directory utente. Aggiungere $HOME/.local/bin al PATH della shell anche per i terminali successivi. Un tht gi\u00e0 presente in quella directory viene aggiornato. Su Windows, eseguire questi comandi dentro WSL2. Il binario tht installato \u00e8 quello Linux di WSL2; il runtime dell\u2019applicazione rimane Docker Desktop. Non usare scripts/install-tht.ps1 come percorso principale di questa prova.","title":"2. Verificare i prerequisiti e installare il comando operatore"},{"location":"install/standalone-manual-it/#3-configurare-e-avviare-linstallazione-locale","text":"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\u00e0 esistenti: umask 077 mkdir -p deploy/local/secrets for name in catalog-runtime-password catalog-migrator-password; do target=\"deploy/local/secrets/$name\" if [ ! -e \"$target\" ]; then (set -C; openssl rand -hex 32 > \"$target\") || exit 1 fi done export THT_CATALOG_RUNTIME_PASSWORD_SOURCE=\"$(pwd -P)/deploy/local/secrets/catalog-runtime-password\" export THT_CATALOG_MIGRATOR_PASSWORD_SOURCE=\"$(pwd -P)/deploy/local/secrets/catalog-migrator-password\" Non rigenerare le password di un catalogo gi\u00e0 inizializzato. Configurare senza avviare i servizi: tht setup --profile local --shell-mode full --shell-default-locale en --configure-only Rispondere ai prompt nel seguente modo: Prompt Valore o regola Installation ID local , salvo necessit\u00e0 di pi\u00f9 installazioni nello stesso clone Deployment profile local DWH API endpoint URL http(s) senza user, password, query o fragment; pu\u00f2 restare vuoto per il solo smoke test LLM API endpoint URL http(s) senza credenziali; pu\u00f2 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\u2019installazione; non inserire password in una riga di comando La configurazione generata \u00e8 locale e ignorata da Git: deploy/local/thothii-installation.yaml deploy/local/operator.env deploy/local/auth/ deploy/local/secrets/ Modificare i segreti solo nei file locali protetti; non committarli. Il file deploy/env/local.env.example \u00e8 un riferimento tracciato; il percorso generato da tht setup , deploy/local/operator.env , \u00e8 quello da usare per questa installazione.","title":"3. Configurare e avviare l\u2019installazione locale"},{"location":"install/standalone-manual-it/#completare-i-file-protetti","text":"Se il setup ha creato template vuoti, inserire i valori con un editor locale: chmod 600 deploy/local/secrets/* \"${EDITOR:-vi}\" deploy/local/secrets/thothii.secrets Il bundle deve contenere solo righe KEY=VALUE per le credenziali effettivamente usate dal modelCatalog . I nomi ammessi e il confine delle credenziali sono descritti nel file locale deploy/secrets/README.md . Non mettere token nelle URL, nel descriptor YAML, nel repository Git o nei comandi copiati nella shell. Per accesso workspace SSH, predisporre anche la chiave privata e il file known_hosts indicati dal setup. Per accesso HTTPS, predisporre il credential file Git e l\u2019eventuale CA. Entrambi devono restare protetti e fuori dal controllo versione. Prima dell'avvio completare anche questi passaggi: 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. Sostituire il modelCatalog generico nel descriptor con la configurazione provider/modelli approvata. I default generati non replicano il Mac esistente. Vedere configurazione Pi/modelli e l'esempio locale deploy/psd/thothii-installation.yaml.example . 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. Completare i file Git del workspace. SSH richiede una chiave deploy autorizzata e known-hosts verificato; HTTPS richiede il credential file e il bundle CA previsti dall'overlay. I template vuoti non consentono l'accesso al repository. Dopo aver modificato la configurazione generata, non rilanciare setup: rifiuta file esistenti con contenuti diversi. Generare le proiezioni ed eseguire la migrazione esplicita indicata sotto. Impostare THT_GIT_ACCESS=https se scelto nel setup. Il blocco usa il nuovo descriptor local con il solo overlay Git; per installazioni personalizzate includere gli overlay aggiuntivi nello stesso ordine del descriptor. INSTALLATION=\"$(pwd -P)/deploy/local/thothii-installation.yaml\" tht --installation \"$INSTALLATION\" installation generate THT_PROJECT=\"thothii-$(printf '%s' \"$INSTALLATION\" | shasum -a 256 | cut -c 1-12)\" THT_GIT_ACCESS=ssh compose=( docker compose --project-name \"$THT_PROJECT\" --project-directory \"$(pwd -P)\" --env-file \"$(pwd -P)/deploy/local/operator.env\" -f compose.yaml -f deploy/compose.local.yaml -f \"deploy/compose.git-$THT_GIT_ACCESS.yaml\" -f deploy/local/generated/compose.models.yaml ) \"${compose[@]}\" config --quiet \"${compose[@]}\" build core frontend \"${compose[@]}\" up -d catalog-db \"${compose[@]}\" run --rm catalog-migrate tht --installation \"$INSTALLATION\" start Fermarsi se un comando fallisce. Il nome progetto coincide con l'hash usato da tht , preservando l'identit\u00e0 dei volumi. catalog-migrate applica le migrazioni Catalog e Memory; tht start non lo esegue automaticamente. Il primo download del modello embedding pu\u00f2 richiedere tempo. Usare questa sequenza legata all'installazione, non run-stack.sh con env/progetto diversi.","title":"Completare i file protetti"},{"location":"install/standalone-manual-it/#4-verificare-linstallazione","text":"Il descriptor generato per l\u2019ID predefinito \u00e8: INSTALLATION=\"$(pwd -P)/deploy/local/thothii-installation.yaml\" test -f \"$INSTALLATION\" bash scripts/verify-standalone-install.sh \"$INSTALLATION\" Il verificatore \u00e8 read-only: esegue tht doctor --json e tht status , senza ristartare lo stack, rigenerare la configurazione o stampare il contenuto dei segreti.","title":"4. Verificare l\u2019installazione"},{"location":"install/standalone-manual-it/#gate-a-smoke-di-piattaforma-su-tutti-e-tre-i-computer","text":"Registrare per ogni macchina: 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 \u00e8 integro, Docker e Compose sono raggiungibili, tht doctor \u00e8 OK, lo stack \u00e8 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\u00e0 HTTP con: curl --fail --silent --show-error http://127.0.0.1:8080/health","title":"Gate A \u2014 smoke di piattaforma, su tutti e tre i computer"},{"location":"install/standalone-manual-it/#gate-b-verifica-funzionale","text":"Eseguire almeno su una macchina con endpoint e credenziali disponibili: Seguire prima Workspace operations 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. aprire http://127.0.0.1:8080 ; autenticarsi con l\u2019account locale configurato; verificare che il workspace configurato sia leggibile; avviare una domanda reale e completare i gate di revisione fino alla SQL finale; fermare e riavviare l\u2019installazione, 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\u00e0 Docker: registrare separatamente l\u2019endpoint o il componente fallito.","title":"Gate B \u2014 verifica funzionale"},{"location":"install/standalone-manual-it/#ciclo-di-vita-quotidiano","text":"Usare il descriptor esplicito quando pi\u00f9 installazioni possono essere scoperte: INSTALLATION=\"$PWD/deploy/local/thothii-installation.yaml\" tht --installation \"$INSTALLATION\" status tht --installation \"$INSTALLATION\" start tht --installation \"$INSTALLATION\" start --build tht --installation \"$INSTALLATION\" logs tht --installation \"$INSTALLATION\" doctor --json tht --installation \"$INSTALLATION\" stop start --build \u00e8 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: \u00e8 un\u2019operazione distruttiva che cancella i dati locali. Per aggiornamenti che richiedono migrazioni, seguire il runbook della release prima dell'avvio.","title":"Ciclo di vita quotidiano"},{"location":"install/standalone-manual-it/#diagnosi-rapida","text":"Sintomo Controllo Docker Engine is not reachable avviare Docker Desktop oppure il servizio Docker e ripetere docker info Windows vede Docker ma Bash fallisce eseguire la guida dentro Ubuntu WSL2 e abilitare l\u2019integrazione 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","title":"Diagnosi rapida"},{"location":"install/standalone-manual-it/#checklist-di-accettazione","text":"[ ] Il clone proviene dal repository Gitea atteso e la revisione \u00e8 stata annotata. [ ] Docker Desktop/Engine e Compose v2 sono disponibili. [ ] Il runtime restituisce un\u2019architettura ammessa. [ ] tht \u00e8 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.","title":"Checklist di accettazione"},{"location":"install/standalone-manual-it/#fuori-perimetro-di-questa-release","text":"Restano attivit\u00e0 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\u2019applicazione.","title":"Fuori perimetro di questa release"},{"location":"install/standalone-manual-it/#documenti-collegati","text":"Install and first start Shell and localization Workspace operations deploy/secrets/README.md (runtime secrets)","title":"Documenti collegati"},{"location":"operations/database-management/","text":"Database management \u00b6 Database Management is the administrative PostgreSQL Metadata Catalog for an external PostgreSQL schema. Its binding and metadata are the sole database source used by workspace preprocessing and the NL\u2192SQL session workflow. What the catalog owns \u00b6 For each workspace identity, an administrator may configure at most one Metadata Catalog binding. It holds the database name, schema, connection binding, write-only encrypted secrets, observed physical schema, optional curated descriptions, generated descriptions, and durable operation history. It does not become the external source of truth. Tables, columns, types, defaults, nullability, primary-key positions, and ordered foreign-key pairs are observations of the source schema and cannot be manually created, renamed, or structurally edited. Descriptions are the editable metadata. Navigate the Fleet Ledger surface \u00b6 Database Management opens Fleet Ledger inside the normal application shell. Only one data grid is shown at a time: choose a database to see its tables, choose a table to see its columns, or open the database's relationships view. Use the emphasized back control or breadcrumb to return to the parent grid. The KPI strip reports tables, columns, sensitive columns, relationships, and description coverage. It uses GET /catalog/metrics without databaseId for installation totals and with databaseId for the current database. Choose a selection-scoped operation from the action selector and then press Run ; unavailable operations remain listed with an explanation. Row-specific actions are the icon controls in the final column, and each navigation or action icon has an immediate conceptual tooltip. An unconfigured workspace exposes Configure catalog directly on its row; there is no global database-creation action and the selected workspace cannot be changed in the configuration form. The master grid keeps three independent states visible: Revision / Evidence comes from the active immutable workspace revision. Filesystem Evidence is materialized with that revision; remote Evidence is reported as configured-but-unverified or as requiring credentials. NL\u2192SQL runtime is calculated from the workspace DWH/Evidence requirements and runtime secret store. It also reports transports, such as SSH, that are diagnostic-only and unsupported by sessions. Metadata Catalog reports whether the installation-local catalog configuration exists, then shows its separately versioned connection-test or synchronization state. Configuration, object details, metadata editors, synchronization history, description history, sensitive-field review, and suggestion-run history open in right-side drawers backed by the production catalog APIs. Closing a history drawer does not cancel a durable background run. Existing permission checks, dirty/busy navigation guards, stale-state handling, and write-only secret behavior continue to apply. For temporary comparison in development or staging, add ?db-ui=legacy ; the parameter is honored only by Vite development or an environment explicitly configured with VITE_DB_MANAGEMENT_LEGACY=true . The separate prototype on port 5173 is not the application and remains available only until the integrated Fleet Ledger surface passes owner acceptance. Configure and test a database \u00b6 Open Database Management and find the repository workspace marked Not configured . Choose Configure catalog on that row. Configure its PostgreSQL catalog binding with postgres_direct , rest_api , or ssh_tunnel and complete the binding fields that the chosen transport requires. Enter secrets only when replacing them. They remain write-only and are never returned by the application. Use Test connection whenever you want an informational connectivity check. Its result does not enable or disable catalog operations. SSH uses a private key, optional key passphrase, mandatory known_hosts , and optional PostgreSQL TLS CA/server name. REST prefers POST /rpc/schema_snapshot ; when it is absent, the catalog may use the same strict v1 snapshot through one read-only POST /rpc/run_query . An unavailable capability, malformed snapshot, or connector error applies no catalog changes. See the schema snapshot contract . Synchronize authoritative schema metadata \u00b6 Schema synchronization reads the external database and reconciles the installation-local catalog. It never changes the source database. Every synchronization attempts a fresh connection when it runs; an unreachable server or rejected credential fails that run without changing catalog data. The available synchronization scopes are tables , columns , relationships , and all , but the UI exposes them at different levels: Location Action Effective scope Database view Synchronize tables All tables in the selected database Database view Synchronize relationships All physical foreign-key relationships in the selected database Database view Synchronize all Tables, columns, and physical relationships in the selected database Tables view Synchronize database tables All tables in the selected database. Selecting a table enables the action, but does not narrow its scope. Tables view Synchronize columns for selected tables Columns belonging to the selected tables Columns view Synchronize columns for this table All columns belonging to the table currently open. Selecting at least one column enables the action, but does not narrow its scope to that column. There is no database-level column action and no synchronization action for an individual column. The selection requirement in the tables and columns views controls whether the action selector can be used; it is not always the same as the synchronization target. The Sync all button in the tables view is the direct shortcut for the full-database scope. Connection tests are informational and are never a synchronization prerequisite. Each synchronization tests its own access while reading the schema; an unavailable connection fails that operation with a connector error. Only one catalog operation can be active for a database at a time; explicit cleanup shares this exclusion. What a synchronization does \u00b6 Every run first creates a durable queued operation and reads a schema snapshot. The scan reports these phases: Connect to the database. Read tables. Read columns and primary-key positions. Read foreign-key relationships. Calculate the planned catalog difference. Apply only the requested scope. The scan currently reads the complete physical snapshot, including foreign keys, even when the requested scope is only tables or columns. This is required by the introspection contract and is why the log can mention foreign-key reading during a table synchronization. Reading those keys does not by itself create or update catalog relationships: Synchronize tables writes table membership and source comments. If a table disappears, its catalog columns and physical relationships are removed through the table cascade. Synchronize columns writes column membership and structural attributes for all tables or for the selected table subset. It does not write physical relationships. Synchronize relationships writes the physical relationships derived from the source foreign keys. It does not create generated or manual logical relationships. Synchronize all applies all three scopes and marks the database schema version as fully synchronized. The run scans first and publishes a durable operation. If it detects a destructive difference, it requires confirmation and re-scans before applying. You can cancel before apply; completed and failed runs remain in history. The live log is delivered over SSE with a polling fallback. The synchronization history records the requested scope, progress phases, planned changes, confirmation, result counts, and errors. Closing the history drawer does not cancel a running operation; it can be reopened from the database synchronization history control. Explicit cleanup is different from source synchronization: administrators can clear selected table/relationship or column/relationship catalog metadata without changing the external source, the connection binding, or secrets. Deleting a table cascades to its columns and relationships. Generate and consolidate descriptions \u00b6 Generated descriptions can be requested for selected tables, selected columns, every eligible target, or targets with a missing generated description. The backend accepts one installation-wide run and processes targets sequentially. Every catalog column has a Sensitive flag, which defaults to false , including after a newly discovered column is synchronized. Before generation, an administrator can run local sensitivity analysis over the selected database, tables, or columns. The analysis combines structural metadata with bounded read-only inspection of source values. It uses no generative AI and no installation-catalog model. Assessments remain an unsaved draft until a human reviews and saves them; the reviewer may reverse any proposal. The page exposes separate histories for description generation and sensitivity analysis. Analysis history stores the local policy version, scope, status, aggregate sensitive , non_sensitive , and unknown counts, timestamps, and sanitized events. It does not store source values, per-column proposals, NER spans, or worker diagnostics; closing an unsaved review discards that draft. The rules, time bounds, and optional CPU-only NER profile are documented in Local sensitivity analysis . For a column with sensitive=false , the worker may read at most five source rows and five representative non-null values through a read-only connector. For sensitive=true , the source query does not request that column's values; deterministic plausible values derived only from its name and type take their place in the model prompt. The prompt does not identify those values as synthetic, so the model can still describe the field as if it had received representative data. Each successful result is persisted immediately. Stop terminates the active helper but retains earlier results. A helper has at most one provider retry; three consecutively exhausted technical batches fail the run. Stale queued/running work is marked interrupted at startup and can be unlocked only when no local worker/helper is live. There is no automatic resume and no public description-generation CLI. Review generated text before copying it into the curated Description field. Because the flag defaults to false , an administrator must review the classification and mark protected fields before starting generation. Changing a flag affects future generations only; existing generated or curated descriptions are not regenerated. Real and substituted samples remain transient and are not persisted or returned to the browser. The database-level Copy generated description to descriptions action applies every non-empty AI-generated table and column description to the corresponding curated Description field in one atomic operation. It skips empty generated descriptions, reports aggregate copied and skipped counts, and retains the generated text. Because this can replace reviewed descriptions, the interface requires explicit confirmation before applying it. The decisions behind this surface are ADRs 0001\u20130011 and the detailed acceptance record is AI catalog description generation acceptance .","title":"Databases and descriptions"},{"location":"operations/database-management/#database-management","text":"Database Management is the administrative PostgreSQL Metadata Catalog for an external PostgreSQL schema. Its binding and metadata are the sole database source used by workspace preprocessing and the NL\u2192SQL session workflow.","title":"Database management"},{"location":"operations/database-management/#what-the-catalog-owns","text":"For each workspace identity, an administrator may configure at most one Metadata Catalog binding. It holds the database name, schema, connection binding, write-only encrypted secrets, observed physical schema, optional curated descriptions, generated descriptions, and durable operation history. It does not become the external source of truth. Tables, columns, types, defaults, nullability, primary-key positions, and ordered foreign-key pairs are observations of the source schema and cannot be manually created, renamed, or structurally edited. Descriptions are the editable metadata.","title":"What the catalog owns"},{"location":"operations/database-management/#navigate-the-fleet-ledger-surface","text":"Database Management opens Fleet Ledger inside the normal application shell. Only one data grid is shown at a time: choose a database to see its tables, choose a table to see its columns, or open the database's relationships view. Use the emphasized back control or breadcrumb to return to the parent grid. The KPI strip reports tables, columns, sensitive columns, relationships, and description coverage. It uses GET /catalog/metrics without databaseId for installation totals and with databaseId for the current database. Choose a selection-scoped operation from the action selector and then press Run ; unavailable operations remain listed with an explanation. Row-specific actions are the icon controls in the final column, and each navigation or action icon has an immediate conceptual tooltip. An unconfigured workspace exposes Configure catalog directly on its row; there is no global database-creation action and the selected workspace cannot be changed in the configuration form. The master grid keeps three independent states visible: Revision / Evidence comes from the active immutable workspace revision. Filesystem Evidence is materialized with that revision; remote Evidence is reported as configured-but-unverified or as requiring credentials. NL\u2192SQL runtime is calculated from the workspace DWH/Evidence requirements and runtime secret store. It also reports transports, such as SSH, that are diagnostic-only and unsupported by sessions. Metadata Catalog reports whether the installation-local catalog configuration exists, then shows its separately versioned connection-test or synchronization state. Configuration, object details, metadata editors, synchronization history, description history, sensitive-field review, and suggestion-run history open in right-side drawers backed by the production catalog APIs. Closing a history drawer does not cancel a durable background run. Existing permission checks, dirty/busy navigation guards, stale-state handling, and write-only secret behavior continue to apply. For temporary comparison in development or staging, add ?db-ui=legacy ; the parameter is honored only by Vite development or an environment explicitly configured with VITE_DB_MANAGEMENT_LEGACY=true . The separate prototype on port 5173 is not the application and remains available only until the integrated Fleet Ledger surface passes owner acceptance.","title":"Navigate the Fleet Ledger surface"},{"location":"operations/database-management/#configure-and-test-a-database","text":"Open Database Management and find the repository workspace marked Not configured . Choose Configure catalog on that row. Configure its PostgreSQL catalog binding with postgres_direct , rest_api , or ssh_tunnel and complete the binding fields that the chosen transport requires. Enter secrets only when replacing them. They remain write-only and are never returned by the application. Use Test connection whenever you want an informational connectivity check. Its result does not enable or disable catalog operations. SSH uses a private key, optional key passphrase, mandatory known_hosts , and optional PostgreSQL TLS CA/server name. REST prefers POST /rpc/schema_snapshot ; when it is absent, the catalog may use the same strict v1 snapshot through one read-only POST /rpc/run_query . An unavailable capability, malformed snapshot, or connector error applies no catalog changes. See the schema snapshot contract .","title":"Configure and test a database"},{"location":"operations/database-management/#synchronize-authoritative-schema-metadata","text":"Schema synchronization reads the external database and reconciles the installation-local catalog. It never changes the source database. Every synchronization attempts a fresh connection when it runs; an unreachable server or rejected credential fails that run without changing catalog data. The available synchronization scopes are tables , columns , relationships , and all , but the UI exposes them at different levels: Location Action Effective scope Database view Synchronize tables All tables in the selected database Database view Synchronize relationships All physical foreign-key relationships in the selected database Database view Synchronize all Tables, columns, and physical relationships in the selected database Tables view Synchronize database tables All tables in the selected database. Selecting a table enables the action, but does not narrow its scope. Tables view Synchronize columns for selected tables Columns belonging to the selected tables Columns view Synchronize columns for this table All columns belonging to the table currently open. Selecting at least one column enables the action, but does not narrow its scope to that column. There is no database-level column action and no synchronization action for an individual column. The selection requirement in the tables and columns views controls whether the action selector can be used; it is not always the same as the synchronization target. The Sync all button in the tables view is the direct shortcut for the full-database scope. Connection tests are informational and are never a synchronization prerequisite. Each synchronization tests its own access while reading the schema; an unavailable connection fails that operation with a connector error. Only one catalog operation can be active for a database at a time; explicit cleanup shares this exclusion.","title":"Synchronize authoritative schema metadata"},{"location":"operations/database-management/#what-a-synchronization-does","text":"Every run first creates a durable queued operation and reads a schema snapshot. The scan reports these phases: Connect to the database. Read tables. Read columns and primary-key positions. Read foreign-key relationships. Calculate the planned catalog difference. Apply only the requested scope. The scan currently reads the complete physical snapshot, including foreign keys, even when the requested scope is only tables or columns. This is required by the introspection contract and is why the log can mention foreign-key reading during a table synchronization. Reading those keys does not by itself create or update catalog relationships: Synchronize tables writes table membership and source comments. If a table disappears, its catalog columns and physical relationships are removed through the table cascade. Synchronize columns writes column membership and structural attributes for all tables or for the selected table subset. It does not write physical relationships. Synchronize relationships writes the physical relationships derived from the source foreign keys. It does not create generated or manual logical relationships. Synchronize all applies all three scopes and marks the database schema version as fully synchronized. The run scans first and publishes a durable operation. If it detects a destructive difference, it requires confirmation and re-scans before applying. You can cancel before apply; completed and failed runs remain in history. The live log is delivered over SSE with a polling fallback. The synchronization history records the requested scope, progress phases, planned changes, confirmation, result counts, and errors. Closing the history drawer does not cancel a running operation; it can be reopened from the database synchronization history control. Explicit cleanup is different from source synchronization: administrators can clear selected table/relationship or column/relationship catalog metadata without changing the external source, the connection binding, or secrets. Deleting a table cascades to its columns and relationships.","title":"What a synchronization does"},{"location":"operations/database-management/#generate-and-consolidate-descriptions","text":"Generated descriptions can be requested for selected tables, selected columns, every eligible target, or targets with a missing generated description. The backend accepts one installation-wide run and processes targets sequentially. Every catalog column has a Sensitive flag, which defaults to false , including after a newly discovered column is synchronized. Before generation, an administrator can run local sensitivity analysis over the selected database, tables, or columns. The analysis combines structural metadata with bounded read-only inspection of source values. It uses no generative AI and no installation-catalog model. Assessments remain an unsaved draft until a human reviews and saves them; the reviewer may reverse any proposal. The page exposes separate histories for description generation and sensitivity analysis. Analysis history stores the local policy version, scope, status, aggregate sensitive , non_sensitive , and unknown counts, timestamps, and sanitized events. It does not store source values, per-column proposals, NER spans, or worker diagnostics; closing an unsaved review discards that draft. The rules, time bounds, and optional CPU-only NER profile are documented in Local sensitivity analysis . For a column with sensitive=false , the worker may read at most five source rows and five representative non-null values through a read-only connector. For sensitive=true , the source query does not request that column's values; deterministic plausible values derived only from its name and type take their place in the model prompt. The prompt does not identify those values as synthetic, so the model can still describe the field as if it had received representative data. Each successful result is persisted immediately. Stop terminates the active helper but retains earlier results. A helper has at most one provider retry; three consecutively exhausted technical batches fail the run. Stale queued/running work is marked interrupted at startup and can be unlocked only when no local worker/helper is live. There is no automatic resume and no public description-generation CLI. Review generated text before copying it into the curated Description field. Because the flag defaults to false , an administrator must review the classification and mark protected fields before starting generation. Changing a flag affects future generations only; existing generated or curated descriptions are not regenerated. Real and substituted samples remain transient and are not persisted or returned to the browser. The database-level Copy generated description to descriptions action applies every non-empty AI-generated table and column description to the corresponding curated Description field in one atomic operation. It skips empty generated descriptions, reports aggregate copied and skipped counts, and retains the generated text. Because this can replace reviewed descriptions, the interface requires explicit confirmation before applying it. The decisions behind this surface are ADRs 0001\u20130011 and the detailed acceptance record is AI catalog description generation acceptance .","title":"Generate and consolidate descriptions"},{"location":"operations/sensitivity-analysis/","text":"Local sensitivity analysis \u00b6 Database Management can assess selected columns without sending their metadata or contents to a generative model. The feature is advisory: it creates a transient review draft, while the catalog's Sensitive Data Flag changes only when an administrator explicitly saves a choice. The administrator may set either value, including overriding a sensitive proposal. Default policy \u00b6 SensitivityClassifier is the only column-level decision point. The versioned sensitivity-v4 policy combines: a structural exclusion for declared bigint primary-key columns and undeclared bigint columns following the exact pk naming convention; their values are non-informative identifiers and are therefore not inspected as possible sensitive content. The evidence distinguishes declared constraints from convention-based inference; normalized column-name rules for direct identifiers, credentials, and health data; validated content rules for email, Italian fiscal code and VAT, passport, identity-card and driving-licence identifiers, phone numbers, IBAN/BIC, payment-card checksums, IP/MAC addresses, URLs, UUIDs, access keys, private-key markers, sensitive keys inside bounded recursive JSON, and a reviewed Italian clinical-term dictionary; a conservative length rule: any observed textual value longer than 500 characters makes the entire column sensitive. One decisive value is enough to classify the column as sensitive and removes it from subsequent passes. Binary or otherwise uninspectable column types are also proposed as sensitive , because their contents cannot be cleared by the textual rules. A completed analysis has only two draft outcomes: sensitive and non_sensitive . Empty or all-null columns are non_sensitive with no_values coverage; a sampled column with no match is non_sensitive with explicit sampled coverage. The administrator remains free to reverse either proposal before saving it. Source reads are database-specific, but decisions are database-independent. PostgreSQL direct and REST run_query adapters project at most 501 characters per value, use only SELECT , and never persist source values. Tables proven to contain at most 1,000 rows are fully scanned. Larger tables are processed breadth-first so every table gets the cheapest pass before any table gets a deeper one: inspect up to 300 non-null values per unresolved column; inspect up to 700 additional values, reaching a 1,000-value target; for unresolved text, JSON, and XML columns only, inspect up to 2,000 additional values, reaching a 3,000-value target. At most two tables are scanned concurrently, and the database adapter groups at most 25 columns in one source query. Each probe or value query has a five-second statement timeout; PostgreSQL-wire reads run in a read-only transaction and always end with rollback. Sampling is bounded and repeatable for a policy version. If a randomized sample is empty or reaches its query timeout, the adapter tries one sequential bounded sample; if that also times out, the source error fails the run and returns no review instead of manufacturing unknown decisions. There is no global sixty-second analysis deadline. Work is bounded by sample counts, per-query timeouts, and early column exits. The operation is interrupted only when its request connection is aborted or the backend restarts. Historical or interrupted run counters named unknown represent columns that were not processed; unknown is not a sensitivity-v4 column assessment. History stores only the policy version, aggregate outcomes, timestamps, and fixed operational events. Sanitized rule IDs are returned in the transient review and shadow report, not persisted. Neither path stores values, matched spans, prompts, or free-form model output. Optional CPU-only GLiNER2 evidence \u00b6 The deterministic engine works without Python NER. An installation may opt into fastino/gliner2-privacy-filter-PII-multi for unresolved short text. It runs in a persistent local Python worker, adds sanitized evidence, and never becomes a second decision point. The worker: loads a local model directory only and forces Hugging Face/Transformers offline mode; starts warming in the background when the backend starts; an analysis never waits for warm-up and skips NER until the worker is ready, so loading cannot consume the run's NER allowance; hides CUDA and HIP devices and loads weights with map_location=\"cpu\" ; starts with a scrubbed environment, then installs a fail-closed seccomp filter that denies network syscalls before accepting source text (the Python socket API is disabled as defense in depth); receives at most two 500-character candidates per table by default, selected breadth-first across unresolved columns, and shares a ten-second NER allowance across the whole run; returns only column ID, normalized label, and confidence; source text and entity spans are not returned or stored; is skipped on timeout, startup failure, invalid output, or absent configuration. No LLM fallback is selected. The pinned model revision is c153999da5f4c509df4322b0c6a1baf3d2c284d7 . GLiNER2 and the model are Apache-2.0; the published mDeBERTa base is MIT. The optional runtime pins gliner2[local]==2.0.0 , transformers==4.57.6 , and the CPU-only PyTorch wheel torch==2.14.0+cpu . It lives in /opt/sensitivity-ner , is not installed in the default core image, and does not install CUDA packages. The current upstream checkpoint was saved by Transformers 5.8 even though GLiNER2 2.0.0 officially requires Transformers <5 ; the resulting tokenizer error is independently reported in GLiNER2 issue 145 . At startup ThothII leaves the pinned model directory unchanged and creates a temporary symlink view that maps the checkpoint's extra_special_tokens list to the Transformers 4 name additional_special_tokens . Any other or ambiguous shape fails closed and leaves the optional NER unavailable. The offline CPU smoke test must remain part of every dependency or model revision update. Prepare and enable the optional profile \u00b6 Download happens during explicit installation, never during inference: ./scripts/fetch-sensitivity-ner-model.sh /absolute/path/to/gliner2-pii The script builds the separate thothii-core:sensitivity-ner image, downloads the exact revision, and writes MODEL_SHA256SUMS . Keep the model directory outside the repository. Then set: export THOTH_ENABLE_SENSITIVITY_NER=1 export THT_SENSITIVITY_NER_MODEL_DIR=/absolute/path/to/gliner2-pii export THT_SENSITIVITY_NER_THREADS=2 ./scripts/run-stack.sh For an operator-managed Compose invocation, include deploy/compose.sensitivity-ner.yaml after the base and installation overlays. The core build argument INSTALL_SENSITIVITY_NER=true installs the optional Python dependencies into their isolated virtualenv. The model mount is read-only. Values above eight threads are rejected; start with two so classification cannot contend heavily with other CPU workloads. Acceptance on a real database \u00b6 Run the first evaluation in shadow mode: read the source with its existing read-only role, do not save proposed flags, and report only aggregate counts, rule IDs, coverage, and timings. Never copy matched values into test output. Use a separately approved, labeled Italian corpus to calculate precision and recall; source values must remain inside the authorized environment. Inside the configured core runtime, the non-mutating command is: npm run sensitivity:shadow -- <workspace-id> It reads catalog metadata and source values but emits one aggregate JSON object with no database, table, column, or source-value detail. It neither creates an analysis run nor updates a flag. Enabling NER by default requires all of these gates: the pinned artifact and MODEL_SHA256SUMS are archived with the installation inventory; the Python dependency/license inventory contains only redistribution-compatible licenses; the CPU benchmark stays within the configured NER allowance and does not use a GPU; the labeled Italian evaluation meets thresholds approved by the product owner. If a gate fails, leave NER disabled. The deterministic policy remains available and produces the binary draft from its scan coverage; no content is sent to an internal or external LLM. Benchmarks from a particular installation are not a guarantee for another database or machine. NER remains opt-in until an approved evaluation establishes that additional findings justify their false-positive rate and operational cost. Keep benchmark and release records with the installation's technical evidence, separate from this operator procedure.","title":"Sensitive columns"},{"location":"operations/sensitivity-analysis/#local-sensitivity-analysis","text":"Database Management can assess selected columns without sending their metadata or contents to a generative model. The feature is advisory: it creates a transient review draft, while the catalog's Sensitive Data Flag changes only when an administrator explicitly saves a choice. The administrator may set either value, including overriding a sensitive proposal.","title":"Local sensitivity analysis"},{"location":"operations/sensitivity-analysis/#default-policy","text":"SensitivityClassifier is the only column-level decision point. The versioned sensitivity-v4 policy combines: a structural exclusion for declared bigint primary-key columns and undeclared bigint columns following the exact pk naming convention; their values are non-informative identifiers and are therefore not inspected as possible sensitive content. The evidence distinguishes declared constraints from convention-based inference; normalized column-name rules for direct identifiers, credentials, and health data; validated content rules for email, Italian fiscal code and VAT, passport, identity-card and driving-licence identifiers, phone numbers, IBAN/BIC, payment-card checksums, IP/MAC addresses, URLs, UUIDs, access keys, private-key markers, sensitive keys inside bounded recursive JSON, and a reviewed Italian clinical-term dictionary; a conservative length rule: any observed textual value longer than 500 characters makes the entire column sensitive. One decisive value is enough to classify the column as sensitive and removes it from subsequent passes. Binary or otherwise uninspectable column types are also proposed as sensitive , because their contents cannot be cleared by the textual rules. A completed analysis has only two draft outcomes: sensitive and non_sensitive . Empty or all-null columns are non_sensitive with no_values coverage; a sampled column with no match is non_sensitive with explicit sampled coverage. The administrator remains free to reverse either proposal before saving it. Source reads are database-specific, but decisions are database-independent. PostgreSQL direct and REST run_query adapters project at most 501 characters per value, use only SELECT , and never persist source values. Tables proven to contain at most 1,000 rows are fully scanned. Larger tables are processed breadth-first so every table gets the cheapest pass before any table gets a deeper one: inspect up to 300 non-null values per unresolved column; inspect up to 700 additional values, reaching a 1,000-value target; for unresolved text, JSON, and XML columns only, inspect up to 2,000 additional values, reaching a 3,000-value target. At most two tables are scanned concurrently, and the database adapter groups at most 25 columns in one source query. Each probe or value query has a five-second statement timeout; PostgreSQL-wire reads run in a read-only transaction and always end with rollback. Sampling is bounded and repeatable for a policy version. If a randomized sample is empty or reaches its query timeout, the adapter tries one sequential bounded sample; if that also times out, the source error fails the run and returns no review instead of manufacturing unknown decisions. There is no global sixty-second analysis deadline. Work is bounded by sample counts, per-query timeouts, and early column exits. The operation is interrupted only when its request connection is aborted or the backend restarts. Historical or interrupted run counters named unknown represent columns that were not processed; unknown is not a sensitivity-v4 column assessment. History stores only the policy version, aggregate outcomes, timestamps, and fixed operational events. Sanitized rule IDs are returned in the transient review and shadow report, not persisted. Neither path stores values, matched spans, prompts, or free-form model output.","title":"Default policy"},{"location":"operations/sensitivity-analysis/#optional-cpu-only-gliner2-evidence","text":"The deterministic engine works without Python NER. An installation may opt into fastino/gliner2-privacy-filter-PII-multi for unresolved short text. It runs in a persistent local Python worker, adds sanitized evidence, and never becomes a second decision point. The worker: loads a local model directory only and forces Hugging Face/Transformers offline mode; starts warming in the background when the backend starts; an analysis never waits for warm-up and skips NER until the worker is ready, so loading cannot consume the run's NER allowance; hides CUDA and HIP devices and loads weights with map_location=\"cpu\" ; starts with a scrubbed environment, then installs a fail-closed seccomp filter that denies network syscalls before accepting source text (the Python socket API is disabled as defense in depth); receives at most two 500-character candidates per table by default, selected breadth-first across unresolved columns, and shares a ten-second NER allowance across the whole run; returns only column ID, normalized label, and confidence; source text and entity spans are not returned or stored; is skipped on timeout, startup failure, invalid output, or absent configuration. No LLM fallback is selected. The pinned model revision is c153999da5f4c509df4322b0c6a1baf3d2c284d7 . GLiNER2 and the model are Apache-2.0; the published mDeBERTa base is MIT. The optional runtime pins gliner2[local]==2.0.0 , transformers==4.57.6 , and the CPU-only PyTorch wheel torch==2.14.0+cpu . It lives in /opt/sensitivity-ner , is not installed in the default core image, and does not install CUDA packages. The current upstream checkpoint was saved by Transformers 5.8 even though GLiNER2 2.0.0 officially requires Transformers <5 ; the resulting tokenizer error is independently reported in GLiNER2 issue 145 . At startup ThothII leaves the pinned model directory unchanged and creates a temporary symlink view that maps the checkpoint's extra_special_tokens list to the Transformers 4 name additional_special_tokens . Any other or ambiguous shape fails closed and leaves the optional NER unavailable. The offline CPU smoke test must remain part of every dependency or model revision update.","title":"Optional CPU-only GLiNER2 evidence"},{"location":"operations/sensitivity-analysis/#prepare-and-enable-the-optional-profile","text":"Download happens during explicit installation, never during inference: ./scripts/fetch-sensitivity-ner-model.sh /absolute/path/to/gliner2-pii The script builds the separate thothii-core:sensitivity-ner image, downloads the exact revision, and writes MODEL_SHA256SUMS . Keep the model directory outside the repository. Then set: export THOTH_ENABLE_SENSITIVITY_NER=1 export THT_SENSITIVITY_NER_MODEL_DIR=/absolute/path/to/gliner2-pii export THT_SENSITIVITY_NER_THREADS=2 ./scripts/run-stack.sh For an operator-managed Compose invocation, include deploy/compose.sensitivity-ner.yaml after the base and installation overlays. The core build argument INSTALL_SENSITIVITY_NER=true installs the optional Python dependencies into their isolated virtualenv. The model mount is read-only. Values above eight threads are rejected; start with two so classification cannot contend heavily with other CPU workloads.","title":"Prepare and enable the optional profile"},{"location":"operations/sensitivity-analysis/#acceptance-on-a-real-database","text":"Run the first evaluation in shadow mode: read the source with its existing read-only role, do not save proposed flags, and report only aggregate counts, rule IDs, coverage, and timings. Never copy matched values into test output. Use a separately approved, labeled Italian corpus to calculate precision and recall; source values must remain inside the authorized environment. Inside the configured core runtime, the non-mutating command is: npm run sensitivity:shadow -- <workspace-id> It reads catalog metadata and source values but emits one aggregate JSON object with no database, table, column, or source-value detail. It neither creates an analysis run nor updates a flag. Enabling NER by default requires all of these gates: the pinned artifact and MODEL_SHA256SUMS are archived with the installation inventory; the Python dependency/license inventory contains only redistribution-compatible licenses; the CPU benchmark stays within the configured NER allowance and does not use a GPU; the labeled Italian evaluation meets thresholds approved by the product owner. If a gate fails, leave NER disabled. The deterministic policy remains available and produces the binary draft from its scan coverage; no content is sent to an internal or external LLM. Benchmarks from a particular installation are not a guarantee for another database or machine. NER remains opt-in until an approved evaluation establishes that additional findings justify their false-positive rate and operational cost. Keep benchmark and release records with the installation's technical evidence, separate from this operator procedure.","title":"Acceptance on a real database"},{"location":"operations/workspaces/","text":"Workspace operations \u00b6 A workspace is curator-owned Git content plus installation-local runtime bindings. It is the boundary between what can be published and what can be used by an installation. Roles and ownership \u00b6 Role Owns Does not own Curator thoth-workspaces.yaml , <id>/workspace.yaml , and Evidence database metadata, installation secrets, or active runtime bindings Installation operator Git source, selected workspace, write-only runtime secrets, validation, connectivity, and preprocessing commits or pushes to the workspace repository Reviewer NL\u2192SQL decisions in a pinned session workspace publication or preprocessing The root catalog has schema_version: 1 and an ordered list of workspace identities. Schema v4 is the only accepted workspace descriptor. Schema v1, v2, and v3 workspace descriptors are rejected before activation. Each catalog entry must have a matching descriptor at <id>/workspace.yaml in the same Git commit. The application validates a complete candidate revision and activates it atomically; invalid content leaves the preceding active revision in place. A v4 descriptor contains only workspace identity and optional Evidence configuration; it does not contain a database or database metadata. Create a clean v4 descriptor with workspace and optional evidence . Do not import the old DWH, diagnostics, annotation, llm_policy , or semantic_index blocks. Configure the database in Database Management. ThothII never rewrites the curator-owned repository during pull. Operator sequence \u00b6 Curate and push a complete repository revision. Do not put DWH passwords, API keys, private keys, or signed URLs in this repository. In the application, update the workspace repository. This fetches and validates the candidate; it never edits the remote repository. Select the workspace. Supply or replace its write-only Evidence runtime secrets, configure its database in Database Management , then run Validate workspace source and Test workspace connections . The workspace connection test uses that same current database configuration for DWH connectivity and also checks the workspace Evidence and installation semantic services. Select it as the installation workspace before creating sessions. Expand Administration in the right sidebar and run Preprocessing . The button is available when all prerequisites are satisfied: it shows Run when preprocessing is required, Run again when the workspace is already current, and Retry after a failure. The same operation is available from the host CLI for unattended administration. Clear , immediately to the left, removes only replaceable Schema/Evidence vectors, LSH, corpus, and checkpoints after an inline confirmation; it preserves Memory and solved questions. --json keeps CLI stdout machine-readable. INSTALLATION=/absolute/path/thothii-installation.yaml WORKSPACE=example-workspace tht --installation \"$INSTALLATION\" workspace inspect --workspace \"$WORKSPACE\" --json tht --installation \"$INSTALLATION\" workspace preprocess run --workspace \"$WORKSPACE\" --json tht --installation \"$INSTALLATION\" workspace preprocess clear --workspace \"$WORKSPACE\" --json The command snapshots tables, columns, descriptions, sensitivity, and active relationships from PostgreSQL, samples eligible DWH values for LSH, and replaces the schema/Evidence vector slices. It is rerunnable but not resumable and has no rollback. Catalog sync and description generation remain separate operations and must already be complete. After clear, the sidebar reports Required and the core rejects new sessions until a complete run succeeds. Clear can be repeated safely: an already absent reference collection or derived path is a no-op, and the separate Memory collection is never a cleanup target. The sidebar retains no run history. If the current prerequisite blocks a start, it explains what must be completed and correctly reports that there is no run log. If the last run failed, it shows only that run's safe stage, error code, and finish time; use docker compose logs core for the corresponding service log. The contract gives exact validation, exit code, and JSON rules in Workspace preprocessing CLI . For Evidence source forms and the schema-v4 descriptor contract, see Workspace Evidence v3 . Transport and revision rules \u00b6 Runtime sessions support direct PostgreSQL and REST bindings. SSH tunnel bindings are diagnostic only for this path, so they cannot admit an NL\u2192SQL session. Database Management and Test workspace connections share the current database binding, including its strict known-host SSH path; the remaining workspace diagnostics cover Evidence and installation semantic services. Every new session pins the active Git revision. Snapshot cleanup retains revisions still referenced by unarchived sessions. A later pull can prepare a future session but cannot alter a resume.","title":"Workspaces"},{"location":"operations/workspaces/#workspace-operations","text":"A workspace is curator-owned Git content plus installation-local runtime bindings. It is the boundary between what can be published and what can be used by an installation.","title":"Workspace operations"},{"location":"operations/workspaces/#roles-and-ownership","text":"Role Owns Does not own Curator thoth-workspaces.yaml , <id>/workspace.yaml , and Evidence database metadata, installation secrets, or active runtime bindings Installation operator Git source, selected workspace, write-only runtime secrets, validation, connectivity, and preprocessing commits or pushes to the workspace repository Reviewer NL\u2192SQL decisions in a pinned session workspace publication or preprocessing The root catalog has schema_version: 1 and an ordered list of workspace identities. Schema v4 is the only accepted workspace descriptor. Schema v1, v2, and v3 workspace descriptors are rejected before activation. Each catalog entry must have a matching descriptor at <id>/workspace.yaml in the same Git commit. The application validates a complete candidate revision and activates it atomically; invalid content leaves the preceding active revision in place. A v4 descriptor contains only workspace identity and optional Evidence configuration; it does not contain a database or database metadata. Create a clean v4 descriptor with workspace and optional evidence . Do not import the old DWH, diagnostics, annotation, llm_policy , or semantic_index blocks. Configure the database in Database Management. ThothII never rewrites the curator-owned repository during pull.","title":"Roles and ownership"},{"location":"operations/workspaces/#operator-sequence","text":"Curate and push a complete repository revision. Do not put DWH passwords, API keys, private keys, or signed URLs in this repository. In the application, update the workspace repository. This fetches and validates the candidate; it never edits the remote repository. Select the workspace. Supply or replace its write-only Evidence runtime secrets, configure its database in Database Management , then run Validate workspace source and Test workspace connections . The workspace connection test uses that same current database configuration for DWH connectivity and also checks the workspace Evidence and installation semantic services. Select it as the installation workspace before creating sessions. Expand Administration in the right sidebar and run Preprocessing . The button is available when all prerequisites are satisfied: it shows Run when preprocessing is required, Run again when the workspace is already current, and Retry after a failure. The same operation is available from the host CLI for unattended administration. Clear , immediately to the left, removes only replaceable Schema/Evidence vectors, LSH, corpus, and checkpoints after an inline confirmation; it preserves Memory and solved questions. --json keeps CLI stdout machine-readable. INSTALLATION=/absolute/path/thothii-installation.yaml WORKSPACE=example-workspace tht --installation \"$INSTALLATION\" workspace inspect --workspace \"$WORKSPACE\" --json tht --installation \"$INSTALLATION\" workspace preprocess run --workspace \"$WORKSPACE\" --json tht --installation \"$INSTALLATION\" workspace preprocess clear --workspace \"$WORKSPACE\" --json The command snapshots tables, columns, descriptions, sensitivity, and active relationships from PostgreSQL, samples eligible DWH values for LSH, and replaces the schema/Evidence vector slices. It is rerunnable but not resumable and has no rollback. Catalog sync and description generation remain separate operations and must already be complete. After clear, the sidebar reports Required and the core rejects new sessions until a complete run succeeds. Clear can be repeated safely: an already absent reference collection or derived path is a no-op, and the separate Memory collection is never a cleanup target. The sidebar retains no run history. If the current prerequisite blocks a start, it explains what must be completed and correctly reports that there is no run log. If the last run failed, it shows only that run's safe stage, error code, and finish time; use docker compose logs core for the corresponding service log. The contract gives exact validation, exit code, and JSON rules in Workspace preprocessing CLI . For Evidence source forms and the schema-v4 descriptor contract, see Workspace Evidence v3 .","title":"Operator sequence"},{"location":"operations/workspaces/#transport-and-revision-rules","text":"Runtime sessions support direct PostgreSQL and REST bindings. SSH tunnel bindings are diagnostic only for this path, so they cannot admit an NL\u2192SQL session. Database Management and Test workspace connections share the current database binding, including its strict known-host SSH path; the remaining workspace diagnostics cover Evidence and installation semantic services. Every new session pins the active Git revision. Snapshot cleanup retains revisions still referenced by unarchived sessions. A later pull can prepare a future session but cannot alter a resume.","title":"Transport and revision rules"},{"location":"usage/memory/","text":"Use and administer Memory \u00b6 Memory stores reusable knowledge for a workspace. It is separate from Evidence sources and from the saved documents of an individual session. Card family Purpose Domain clarification Define a term or interpretation, with its scope. SQL rule Explain how to construct SQL and why. Solved question Retain an approved question and SQL as a consultative example. Explained error Record a correction and its rationale. Browse and edit \u00b6 Open Administration \u2192 Memory management and select the workspace. Administration requires the appropriate permissions. You can search, filter, open a card's complete content, edit it, manage its dependencies and links, or explicitly confirm deletion. Browsing and editing require the PostgreSQL archive but do not require an active session or a working DWH or search index. Cards retain their identity and origin when edited; there is no editorial revision history. Deleting a card also removes its links and dependencies, not the other cards or the workspace's Evidence. Links connect cards in the same workspace. Record scope and physical dependencies carefully so knowledge is not applied to unrelated databases, tables or columns. Saved content and search availability \u00b6 Saving a card and updating its search index are different outcomes. Saved, index update incomplete means the content is already in the archive but is not ready for recall. Use Pending index updates to retry. Do not create a duplicate card to work around an indexing failure. A restart does not discard the pending operation. Qdrant is a rebuildable search projection, not the authoritative archive. Rebuilding it does not recover deleted cards from old sessions or vector payloads. Back up the authoritative installation data before maintenance. After a successful physical schema synchronization, cards dependent on removed database objects can be deleted. Workspace-wide cards and unrelated dependencies remain. Review the synchronization result and any pending cleanup before starting another synchronization. Memory in a reviewed session \u00b6 The workflow proposes relevant clarifications, rules and examples. A search result is not approval: the reviewer decides whether it applies. At the final Memory review, select the additions or updates worth retaining, edit their content and scope, or decline them all. Finalizing a session does not silently approve every proposed card. Approved SQL is read-only at that final review. To change the solution, return to SQL review. See the workflow guide and user guide .","title":"Memory"},{"location":"usage/memory/#use-and-administer-memory","text":"Memory stores reusable knowledge for a workspace. It is separate from Evidence sources and from the saved documents of an individual session. Card family Purpose Domain clarification Define a term or interpretation, with its scope. SQL rule Explain how to construct SQL and why. Solved question Retain an approved question and SQL as a consultative example. Explained error Record a correction and its rationale.","title":"Use and administer Memory"},{"location":"usage/memory/#browse-and-edit","text":"Open Administration \u2192 Memory management and select the workspace. Administration requires the appropriate permissions. You can search, filter, open a card's complete content, edit it, manage its dependencies and links, or explicitly confirm deletion. Browsing and editing require the PostgreSQL archive but do not require an active session or a working DWH or search index. Cards retain their identity and origin when edited; there is no editorial revision history. Deleting a card also removes its links and dependencies, not the other cards or the workspace's Evidence. Links connect cards in the same workspace. Record scope and physical dependencies carefully so knowledge is not applied to unrelated databases, tables or columns.","title":"Browse and edit"},{"location":"usage/memory/#saved-content-and-search-availability","text":"Saving a card and updating its search index are different outcomes. Saved, index update incomplete means the content is already in the archive but is not ready for recall. Use Pending index updates to retry. Do not create a duplicate card to work around an indexing failure. A restart does not discard the pending operation. Qdrant is a rebuildable search projection, not the authoritative archive. Rebuilding it does not recover deleted cards from old sessions or vector payloads. Back up the authoritative installation data before maintenance. After a successful physical schema synchronization, cards dependent on removed database objects can be deleted. Workspace-wide cards and unrelated dependencies remain. Review the synchronization result and any pending cleanup before starting another synchronization.","title":"Saved content and search availability"},{"location":"usage/memory/#memory-in-a-reviewed-session","text":"The workflow proposes relevant clarifications, rules and examples. A search result is not approval: the reviewer decides whether it applies. At the final Memory review, select the additions or updates worth retaining, edit their content and scope, or decline them all. Finalizing a session does not silently approve every proposed card. Approved SQL is read-only at that final review. To change the solution, return to SQL review. See the workflow guide and user guide .","title":"Memory in a reviewed session"}]}