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

docs: converge operator guidance on tht

Browse Source
This commit is contained in:
marcopan
2026-08-19 16:12:11 +02:00
parent 32a17d83a9
commit 1184b6db16
29 changed files with 544 additions and 380 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/contracts/tht-dwh.md
+1 -1
View File
@@ -86,7 +86,7 @@ workspace://<workspace-id>@v1:<sha256 of the canonical effective configuration>
```
It is the same for the operator CLI and for application sessions, because both derive it from the
same rendered configuration. That is the guarantee that the work prepared by `thothctl` is exactly
same rendered configuration. That is the guarantee that the work prepared by `tht` is exactly
what the sessions will consume.
## Why a rerun can be instant or take minutes
docs/contracts/thothctl-pi.md → docs/contracts/tht-pi.md
+26 -26
View File
@@ -1,19 +1,19 @@
# `thothctl pi` lifecycle contract
# `tht pi` lifecycle contract
`thothctl` is the only component that drives Docker lifecycle operations. The `core` container
`tht` is the only component that drives Docker lifecycle operations. The `core` container
does not mount a Docker socket, and Pi is never updated in a running container.
## Inspection and configuration
```text
thothctl pi status
thothctl pi doctor
thothctl pi test
thothctl pi logs
thothctl pi configure
tht pi status
tht pi doctor
tht pi test
tht pi logs
tht pi configure
```
When `--installation` is omitted, `thothctl` first uses `THOTHII_INSTALLATION` and otherwise
When `--installation` is omitted, `tht` first uses `THOTHII_INSTALLATION` and otherwise
discovers one valid `thothii-installation.yaml` in the current project tree, including an immediate
`deploy/*` directory. Use `--installation /absolute/path/thothii-installation.yaml` as an explicit
override when the descriptor is outside that tree or more than one installation is available.
@@ -30,7 +30,7 @@ models come from the backend's closed model list, and the model choices are rest
selected provider. In non-interactive use, all choices must be explicit:
```text
thothctl pi configure \
tht pi configure \
--provider zai --model glm-5.2 --thinking medium
```
@@ -55,16 +55,16 @@ store.
## Supported Compose entry points and current image
Use `thothctl start`, `stop`, `status`, `logs`, and `doctor` for ordinary installation lifecycle
operations. All `thothctl` Compose commands automatically include the installation-specific
Use `tht start`, `stop`, `status`, `logs`, and `doctor` for ordinary installation lifecycle
operations. All `tht` Compose commands automatically include the installation-specific
durable selector when it exists:
```text
<projectDirectory>/.thothctl/<installation-id>/current-image.yaml
<projectDirectory>/.tht/<installation-id>/current-image.yaml
```
This selector is part of the supported installation state: it keeps a verified Pi image selected
across a fresh `thothctl` process, stop/start, reconcile, and source checkout whose base image is
across a fresh `tht` process, stop/start, reconcile, and source checkout whose base image is
digest-pinned. Do not delete or hand-edit it. Direct raw `docker compose` lifecycle commands bypass
this protection and are unsupported. Advanced documented Compose rendering must use
`scripts/compose-with-preflight.sh` and include the same selector with `-f` when present; connector
@@ -75,7 +75,7 @@ secret overrides must never bypass that preflight wrapper.
Configuration reload is a separate lifecycle operation from an image update:
```text
thothctl pi restart --yes [--drain]
tht pi restart --yes [--drain]
```
`--yes` is required after reviewing the planned core recreation. Restart activates the durable
@@ -95,8 +95,8 @@ identity, and the complete persistence-mount fingerprint.
Restart and update keep separate recovery state:
```text
<projectDirectory>/.thothctl/<installation-id>/restart-state.json
<projectDirectory>/.thothctl/<installation-id>/update-state.json
<projectDirectory>/.tht/<installation-id>/restart-state.json
<projectDirectory>/.tht/<installation-id>/update-state.json
```
The files are mode `0600` and share one installation lifecycle lock, so restart, update, and
@@ -112,8 +112,8 @@ recovery rather than deleting recovery material.
The normal update uses the repository's pinned version and build source automatically:
```text
thothctl pi update
thothctl pi update --version 0.81.0
tht pi update
tht pi update --version 0.81.0
```
With no `--version`, the command reads the single default `ARG PI_VERSION=<version>` from
@@ -124,10 +124,10 @@ command, drains active sessions without terminating them, builds the candidate,
Advanced registry updates remain available and require an immutable digest:
```text
thothctl pi update \
tht pi update \
--version 0.81.0 --source build --yes --drain
thothctl pi update \
tht pi update \
--version 0.81.0 --source pull \
--image registry.example.invalid/thothii-core@sha256:<64-lowercase-hex-digits> --yes
```
@@ -170,9 +170,9 @@ non-secret rendered configuration; and the complete persistence-mount fingerprin
Recovery state and lock diagnostics live under:
```text
<projectDirectory>/.thothctl/<installation-id>/update-state.json
<projectDirectory>/.thothctl/<installation-id>/restart-state.json
<projectDirectory>/.thothctl/<installation-id>/*.lock.owner.json
<projectDirectory>/.tht/<installation-id>/update-state.json
<projectDirectory>/.tht/<installation-id>/restart-state.json
<projectDirectory>/.tht/<installation-id>/*.lock.owner.json
```
Each recovery file is mode `0600`. Update state records transaction-scoped image identities, mount
@@ -195,7 +195,7 @@ gate can open.
For a failed update with `update-state.json`, first run:
```text
thothctl pi rollback --yes
tht pi rollback --yes
```
Rollback restores the image recorded in update state, but it checks restart state before making any
@@ -206,8 +206,8 @@ reported problem, then use maintenance recovery.
Inspect and clean a stale durable gate with:
```text
thothctl pi maintenance status
thothctl pi maintenance recover --yes
tht pi maintenance status
tht pi maintenance recover --yes
```
`maintenance recover` restores the captured restart image pin and lifecycle override when needed,
docs/contracts/workspace-preprocessing-cli.md
+13 -13
View File
@@ -1,42 +1,42 @@
# Workspace preprocessing CLI contract
`thothctl` is the only supported host entrypoint for workspace preprocessing.
`tht` is the only supported host entrypoint for workspace preprocessing.
## Invocation
```text
thothctl --installation <absolute>/thothii-installation.yaml workspace inspect
tht --installation <absolute>/thothii-installation.yaml workspace inspect
--workspace <id> [--json]
thothctl --installation <absolute>/thothii-installation.yaml workspace preprocess dwh
tht --installation <absolute>/thothii-installation.yaml workspace preprocess dwh
--workspace <id> [--resume <32hex>] [--json]
thothctl --installation <absolute>/thothii-installation.yaml workspace schema suggest-fks
tht --installation <absolute>/thothii-installation.yaml workspace schema suggest-fks
--workspace <id>
[--from-sql <regular-file>]... [--assume <column=table>]...
[--output <new-file>] [--json]
thothctl --installation <absolute>/thothii-installation.yaml workspace schema check
tht --installation <absolute>/thothii-installation.yaml workspace schema check
--workspace <id>
[--annotations <regular-file> --reviewed-candidates <sha256:hex>]
[--json]
thothctl --installation <absolute>/thothii-installation.yaml workspace schema accept
tht --installation <absolute>/thothii-installation.yaml workspace schema accept
--workspace <id> --run <32hex> --yes [--json]
thothctl --installation <absolute>/thothii-installation.yaml workspace index-schema
tht --installation <absolute>/thothii-installation.yaml workspace index-schema
--workspace <id> [--json]
thothctl --installation <absolute>/thothii-installation.yaml workspace preprocess evidence
tht --installation <absolute>/thothii-installation.yaml workspace preprocess evidence
--workspace <id> [--dry-run] [--resume <32hex>] [--json]
thothctl --installation <absolute>/thothii-installation.yaml workspace preprocess run
tht --installation <absolute>/thothii-installation.yaml workspace preprocess run
--workspace <id> [--resume <32hex>] [--json]
thothctl --installation <absolute>/thothii-installation.yaml workspace vector inspect
tht --installation <absolute>/thothii-installation.yaml workspace vector inspect
--workspace <id> [--json]
thothctl --installation <absolute>/thothii-installation.yaml workspace vector rebuild
tht --installation <absolute>/thothii-installation.yaml workspace vector rebuild
--workspace <id> --collection <name> --confirm <name> --destroy [--json]
```
@@ -120,7 +120,7 @@ thothctl --installation <absolute>/thothii-installation.yaml workspace vector re
## Container boundary
`thothctl` resolves the selected `core` image from the rendered installation, converts it to an immutable local image ID, writes a one-shot final override that pins both `core` and `workspace-maintenance` to that ID with `pull_policy: never`, and runs only:
`tht` resolves the selected `core` image from the rendered installation, converts it to an immutable local image ID, writes a one-shot final override that pins both `core` and `workspace-maintenance` to that ID with `pull_policy: never`, and runs only:
```text
docker compose run --rm --no-deps --no-TTY --name <owned-name> workspace-maintenance <fixed-command>
@@ -148,7 +148,7 @@ The request is streamed as one schema-versioned JSON document over stdin. Public
}
```
`thothctl --json` parses the operator stdout strictly and re-encodes only the public fields above.
`tht --json` parses the operator stdout strictly and re-encodes only the public fields above.
`evidence_materialization_required` is retained for pre-P6 compatibility; since P6, filesystem
Evidence is materialized at activation and preprocesses directly.