docs: reorganize operational documentation

2026-08-29 20:08:48 +02:00
parent d504b1def1
commit 0ce05869cf
10 changed files with 371 additions and 337 deletions
@@ -0,0 +1,65 @@
+# 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`, Evidence, and curated schema annotations | 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. Each entry
+must have a matching schema-v3 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.
+
+## 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 runtime secrets, then run **Validate
+   workspace source** and **Test workspace connections**.
+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.
+
+```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
+```
+
+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:
+
+```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
+```
+
+The contract gives exact validation, exit code, and JSON rules in
+[Workspace preprocessing CLI](../contracts/workspace-preprocessing-cli.md). For Evidence source
+forms and the schema-v3 descriptor contract, see
+[Workspace Evidence v3](../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 has its own
+strict known-host SSH path for connection tests and schema synchronization.
+
+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.