ThothII/docs/operations/workspaces.md

Workspace operations

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

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→SQL 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

1. Curate and push a complete repository revision. Do not put DWH passwords, API keys, private keys, or signed URLs in this repository.
2. In the application, update the workspace repository. This fetches and validates the candidate; it never edits the remote repository.
3. 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.
4. Select it as the installation workspace before creating sessions.
5. 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

Runtime sessions support direct PostgreSQL and REST bindings. SSH tunnel bindings are diagnostic only for this path, so they cannot admit an NL→SQL 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.