feat: complete catalog-driven preprocessing

docs/operations/workspaces.md

@@ -7,7 +7,7 @@ boundary between what can be published and what can be used by an installation.
 
 | Role | Owns | Does not own |
 | --- | --- | --- |
-| Curator | `thoth-workspaces.yaml`, `<id>/workspace.yaml`, Evidence, and curated schema annotations | installation secrets or active runtime bindings |
+| 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 |
 
@@ -20,14 +20,14 @@ Schema v4 is the only accepted workspace descriptor. Schema v1, v2, and v3 works
 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.
+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 -->
-To convert a v3 descriptor before committing it, set `workspace.schema_version` to `4`, remove
-`llm_policy`, and remove `semantic_index`. Database, Evidence, diagnostics, and binding data remain
-unchanged. Validate the resulting v4 repository revision before activation; ThothII never rewrites
-the curator-owned repository during pull.
+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
@@ -41,29 +41,36 @@ the curator-owned repository during pull.
    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. Use the host CLI for preprocessing. It dispatches a profile-gated maintenance service and
-   returns a single structured result; `--json` keeps stdout machine-readable.
+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 dwh --workspace "$WORKSPACE" --json
-tht --installation "$INSTALLATION" workspace preprocess evidence --workspace "$WORKSPACE" --json
+tht --installation "$INSTALLATION" workspace preprocess run --workspace "$WORKSPACE" --json
+tht --installation "$INSTALLATION" workspace preprocess clear --workspace "$WORKSPACE" --json
 ```
 
-For the full DWH → review → schema-index → Evidence chain, run
-`workspace preprocess run`. It may stop with `manual_review_required` when FK candidates need a
-curator decision. Publish the reviewed annotations, update the repository, then accept that exact
-run and resume it:
+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.
 
-```sh
-tht --installation "$INSTALLATION" workspace schema accept \
-  --workspace "$WORKSPACE" --run <run-id> --yes --json
-tht --installation "$INSTALLATION" workspace preprocess run \
-  --workspace "$WORKSPACE" --resume <run-id> --json
-```
+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](../contracts/workspace-preprocessing-cli.md). For Evidence source