# 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 |

<!-- non-workspace-migration:start -->
The root catalog has `schema_version: 1` and an ordered list of workspace identities.
<!-- non-workspace-migration:end -->

<!-- workspace-descriptor-contract:start -->
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.
<!-- workspace-descriptor-contract:end -->

<!-- non-workspace-migration:start -->
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.
<!-- non-workspace-migration:end -->

## 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.

```sh
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](https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/docs/contracts/workspace-preprocessing-cli.md). For Evidence source
forms and the schema-v4 descriptor contract, see
[Workspace Evidence v3](https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/docs/contracts/workspace-evidence-v3.md).

## 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.