mptyl/ThothII
1
0
Fork 0
Code Issues 25 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: define the P1.1 registry layout and curator flow

Browse Source
This commit is contained in:
marcopan
2026-08-11 15:22:57 +02:00
parent a071e0baff
commit c2f33e58d7
5 changed files with 196 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+29 -10
View File
@@ -57,18 +57,37 @@ diagnostics are exposed by `tht doctor` and do not prevent the UI from starting.
Workspace descriptors are shared through a validated Git repository while endpoint bindings and
secret files remain installation-local. Use the [local Mac/PC installation manual](docs/install/local-workspace-registry.md)
for Docker Desktop or a local engine, and the [server installation manual](docs/install/server-workspace-registry.md)
for the Gitea, reverse-proxy, backup, upgrade, and recovery workflow. The isolated deployment
exercise is `./scripts/workspace-registry-smoke.sh`; both manuals are checked with
`./scripts/verify-workspace-install-docs.sh --profile local` or `--profile server`.
for Docker Desktop or a local engine, the [server installation manual](docs/install/server-workspace-registry.md)
for the Gitea, reverse-proxy, backup, upgrade, and recovery workflow, and the
[P1→P1.1 migration guide](docs/migrations/p1-to-p1-1-registry-layout.md) before upgrading an
older flat-layout registry.
The operator workflow is: update and review canonical YAML in the shared Git remote, **Pull latest
registry** from each ThothII installation, run **Validate workspace** and **Test on this
installation**, then select the workspace locally before creating sessions. Each new session pins
the Git revision it used; a later pull or publish cannot change a Resume. Snapshot cleanup retains
every revision referenced by an open, closed, or failed unarchived session. It reconciles from the
The curator-owned repository layout is:
```text
thoth-workspaces.yaml
<id>/workspace.yaml
<id>/evidence/**
workspace-docs/<id>/{contract.env.example,README.md}
```
`thoth-workspaces.yaml` uses the `schema_version` value `1` and the ordered `workspaces` list of
`{id, name, description?}` entries. It is authoritative for workspace ID, name, description, and
display order. The API may create `<id>/workspace.yaml` only when the catalog slot already exists
and the descriptor is absent. A pulled catalog-only slot reports `configuration_required`. After
bootstrap, existing descriptors remain curator-owned and change only through curator Git commit,
push, and installation pull. The API never writes `thoth-workspaces.yaml` or `<id>/evidence/**`;
its generated docs live only at `workspace-docs/<id>/{contract.env.example,README.md}`.
The operator workflow is: curate catalog/descriptor/Evidence changes in Git, commit and push,
**Pull latest registry** from each ThothII installation, run **Validate workspace** and **Test on
this installation**, then select the workspace locally before creating sessions. Each new session
pins the Git revision it used; a later pull cannot change a Resume. Snapshot cleanup retains every
revision referenced by an open, closed, or failed unarchived session. It reconciles from the
single local installation list or from a server administrator's complete session list, never from
a remote user's partial list.
a remote user's partial list. The isolated deployment exercise is
`./scripts/workspace-registry-smoke.sh`; both manuals are checked with
`./scripts/verify-workspace-install-docs.sh --profile local` or `--profile server`.
<!-- workspace-descriptor-contract:start -->
Schema v3 is the only accepted workspace descriptor. Schema v1 and v2 workspace descriptors are