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

docs: describe read-only workspace runtime configuration

Browse Source
This commit is contained in:
marcopan
2026-08-14 18:01:02 +02:00
parent 422f1d47b4
commit ab33e0ed0a
26 changed files with 511 additions and 911 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/install/local-workspace-registry.md
+139 -293
View File
@@ -1,312 +1,158 @@
# Local workspace-registry installation (Mac and PC)
# Local workspace repository installation (macOS, Windows, and Linux)
Complete the [local PC/Mac/Linux installation](local.md) first. This guide continues with the
Git-backed workspace source of truth, installation-local connector bindings, and diagnostics. Use
the [Pi management manual](pi-management.md) for provider configuration and image recovery.
This guide runs a single-user ThothII registry on Docker Desktop (macOS or Windows) or a local
Linux Docker Engine. It is intentionally loopback-only. Git is shared; the checkout, DWH
bindings, credentials, and session data are local, while internal Qdrant/Ollama ship in the
Compose stack. Never put credentials in workspace YAML, Git, browser drafts, diagnostics, or
`.env.example`.
This manual connects a local ThothII installation to one remote Git repository hosted by a Git
server such as GitHub, GitLab, or Gitea. ThothII is a read-only consumer: it fetches,
validates, and activates workspace revisions, but never edits, commits, pushes, or publishes them.
## Architecture ownership contract
| Component | Ownership | Operator contract |
| --- | --- | --- |
| DWH | External | Installation-local endpoint/binding; never bundled into the Compose semantic stack. |
| LLM | External | Installation-local endpoint/policy choice outside the internal semantic services. |
| Qdrant | Internal | Mandatory private Compose semantic service; persistent `qdrant-data` volume. |
| Ollama embedding | Internal | Mandatory private Compose semantic service for `qwen3-embedding:0.6b`. |
## Host preprocessing (P2)
The installed native `thothctl` is the only host entrypoint for workspace preprocessing
(introspection+LSH, FK review, schema indexing, HTTP Evidence). Use
`thothctl --installation <thothii-installation.yaml> workspace <command> --workspace <id> [--json]`
per `docs/contracts/workspace-preprocessing-cli.md` and the P2 walkthrough in
`docs/testing/p2-p6-manual-verification.md`. Preprocessing runs through the profile-gated
`workspace-maintenance` Compose service; it never starts a backend/Pi/frontend listener and never
attaches Git credentials.
## Effective configuration and `.tht-dwh` (P3)
Prepared DWH generations are reusable and safe: `thothctl` and the application derive the same
canonical effective configuration and logical identity, so prepared work is reused when nothing
relevant changed and refused when the database/endpoint/identity changed. See
`docs/contracts/tht-dwh.md` for generations, `OWNER.json`, `ACTIVE`, fingerprints, migration and
recovery. A content-only or Evidence-only change never forces a full re-introspection.
## Prerequisites
- macOS: Docker Desktop, Git, and sufficient volume disk space. Git Credential Manager is useful
for HTTPS sign-in.
- Windows: Docker Desktop with WSL2, Git for Windows, and the clone enabled in Docker file sharing.
Use absolute paths/WSL paths; PowerShell uses `;` rather than `:` in `COMPOSE_FILE`.
- Linux PC: Docker Engine, Compose plugin, Git, and a user permitted to run Docker.
- Outbound access to the Git remote. A local installation needs no inbound firewall rule.
Keep the operator `.env` and `installation-secrets/` outside the workspace-registry Git checkout.
On macOS/Linux use mode `0600` for individual secret files. On Windows apply an ACL that grants
read access only to the Docker Desktop user. Do not use an empty file to silently bypass a selected
authentication method.
## Git remote: SSH and HTTPS
Create one private repository such as `thoth-workspaces.git`. It contains the curator-owned root
catalog, one directory per workspace, optional embedded Evidence trees, and generated public docs:
```text
registry.git/
├── thoth-workspaces.yaml
├── <workspace-id>/
│ ├── workspace.yaml
│ └── evidence/...
└── workspace-docs/
└── <workspace-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; `<workspace-id>/workspace.yaml` must match that metadata exactly, while
`workspace-docs` remains the reserved top-level generated-docs directory.
For SSH, use a scoped deploy key, a verified `known_hosts` file, and strict host-key checking. For
HTTPS, use Git Credential Manager or a secret-manager-created credentials file. Mount a private
HTTPS CA as its own file. Do not disable host or certificate verification. The base Compose file
does not mount a Git credential: add exactly one optional `deploy/compose.git-ssh.yaml` or
`deploy/compose.git-https.yaml` override, so unused credential paths are never bind-mounted.
```dotenv
THT_WORKSPACE_GIT_REMOTE=ssh://git@git.example.invalid/platform/thoth-workspaces.git
THT_WORKSPACE_GIT_BRANCH=main
THT_WORKSPACE_INSTALLATION_ID=local-laptop
THT_SOURCE_ROOT=/absolute/path/to/ThothII
PI_AUTH_FILE=/absolute/path/installation-secrets/pi-auth.json
THT_SECRETS_FILE=/absolute/path/installation-secrets/thothii.secrets
THT_WORKSPACE_GIT_SSH_KEY_FILE=/absolute/path/installation-secrets/git-ssh-key
THT_WORKSPACE_GIT_KNOWN_HOSTS_FILE=/absolute/path/installation-secrets/git-known-hosts
THT_WORKSPACE_GIT_CA_FILE=/absolute/path/installation-secrets/git-ca.pem
```
For HTTPS set `THT_WORKSPACE_GIT_CREDENTIALS_FILE` instead of the SSH key/known-hosts pair. Remote
and branch are non-secret; every `*_FILE` is a local path whose content never enters Git or logs.
## Curator flow for shared-registry Evidence
Follow this order; the [canonical Evidence contract](../contracts/workspace-evidence-v3.md) defines
the source shapes and safety boundary.
1. Clone the one shared registry, or update the review clone with `git pull --ff-only`.
2. Keep `thoth-workspaces.yaml` curator-owned. It 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.
3. For an existing workspace, edit `<id>/workspace.yaml` and any embedded `<id>/evidence/**`, then
commit and push.
4. For a new workspace, add the catalog slot first. If you want ThothII to bootstrap the
descriptor, leave `<id>/workspace.yaml` absent, commit and push, then pull that commit into the
installation; the slot appears as `configuration_required`.
5. The API may create `<id>/workspace.yaml` only when the catalog slot already exists and no Git
object exists at that path in the exact pulled base commit.
6. After bootstrap, existing descriptors change only through curator Git commit/push and
installation pull. The API never writes `thoth-workspaces.yaml` or `<id>/evidence/**`.
7. Inspect `workspace-docs/<id>/contract.env.example` and `workspace-docs/<id>/README.md`.
8. Provision only the selected Evidence `*_FILE` files outside Git and strictly below a root in
`THT_WORKSPACE_SECRET_ROOTS`; add matching host-only `*_SOURCE` paths for the generated
connector override.
9. Render or acquire the runtime config, then run `tht config check -c <path>`.
10. Stop: P2/P6 later performs preprocessing and materialization.
For example, a signed-HTTP workspace and a different static-S3 workspace can use these host-only
connector sources; the values are paths, not file contents:
```dotenv
THT_WS_SIGNED_HTTP_EVIDENCE_SIGNED_URLS_SOURCE=/absolute/path/installation-secrets/signed-http-evidence-urls.json
THT_WS_STATIC_S3_EVIDENCE_ACCESS_KEY_SOURCE=/absolute/path/installation-secrets/static-s3-evidence-access-key
THT_WS_STATIC_S3_EVIDENCE_SECRET_KEY_SOURCE=/absolute/path/installation-secrets/static-s3-evidence-secret-key
THT_WS_STATIC_S3_EVIDENCE_SESSION_TOKEN_SOURCE=/absolute/path/installation-secrets/static-s3-evidence-session-token
```
The descriptor and declared filesystem root are validated at the same registry commit. The
browser shows a read-only Evidence summary, while exports omit Evidence bytes.
## Shared Git values, local bindings, and secret files
| Location | Contains | Never contains |
| --- | --- | --- |
| Git workspace repository | schema v3 YAML, generated binding names, LLM policy, and semantic-index identity | installation hostnames, keys, passwords, certificates, SSH keys |
| local `.env` | remote, branch, installation ID, `THT_WORKSPACE_BINDINGS_ENV_FILE`, and secret source paths | secret contents or `THT_WS_*` values |
| workspace bindings env file | only `THT_WS_*` transport, endpoint, user, and `/run/secrets/...` path bindings | secret contents or unrelated application settings |
| local secret directory | Git credentials/key, known hosts, CA, connector secret files | a copied registry checkout |
| Docker volumes | registry checkout/snapshots/state/locks and local data | host-only secret source files |
The persistent volume is `/data/workspace-registry`:
```text
repo/ # persistent Git checkout
snapshots/ # immutable validated revisions used by sessions
state/ # active revision and registry state
locks/ # short-lived registry synchronization locks
```
Installation variables are deterministic: `north-star-research` becomes `NORTH_STAR_RESEARCH`, and every name
is `THT_WS_<NAMESPACE>_<ROLE>_<SUFFIX>`. Copy
[the bindings env example](examples/workspace-bindings.env.example) to an untracked operator file
and set its absolute path as `THT_WORKSPACE_BINDINGS_ENV_FILE`. It is loaded only into `core`.
Credentials and certificates use `*_FILE` path variables that must point inside `/run/secrets`.
## Direct PostgreSQL, REST, and SSH tunnel bindings
Set only fields for the selected transport in the dedicated bindings env file. Canonical YAML keeps
database/schema shared in Git. Every `*_FILE=/run/secrets/<target>` binding needs one matching
host-only `*_SOURCE` path in operator `.env`. Generate the untracked connector override from those
two files during bootstrap; do not copy or maintain a workspace-specific Compose override.
```dotenv
# Direct PostgreSQL
THT_WS_NORTH_STAR_RESEARCH_DWH_TRANSPORT=postgres_direct
THT_WS_NORTH_STAR_RESEARCH_DWH_HOST=dwh.example.invalid
THT_WS_NORTH_STAR_RESEARCH_DWH_PORT=5432
THT_WS_NORTH_STAR_RESEARCH_DWH_USER=thoth_reader
THT_WS_NORTH_STAR_RESEARCH_DWH_PASSWORD_FILE=/run/secrets/north-star-research-dwh-password
```
```dotenv
# REST; an API-key file is needed only for a declared bearer/x-api-key diagnostic.
THT_WS_NORTH_STAR_RESEARCH_DWH_TRANSPORT=rest_api
THT_WS_NORTH_STAR_RESEARCH_DWH_BASE_URL=https://dwh.example.invalid
THT_WS_NORTH_STAR_RESEARCH_DWH_API_KEY_FILE=/run/secrets/north-star-research-dwh-api-key
```
```dotenv
# SSH tunnel diagnostic only; runtime sessions are fail-closed in this release.
THT_WS_NORTH_STAR_RESEARCH_DWH_TRANSPORT=ssh_tunnel
THT_WS_NORTH_STAR_RESEARCH_DWH_USER=thoth_reader
THT_WS_NORTH_STAR_RESEARCH_DWH_PASSWORD_FILE=/run/secrets/north-star-research-dwh-password
THT_WS_NORTH_STAR_RESEARCH_DWH_SSH_HOST=bastion.example.invalid
THT_WS_NORTH_STAR_RESEARCH_DWH_SSH_PORT=22
THT_WS_NORTH_STAR_RESEARCH_DWH_SSH_USER=thoth_tunnel
THT_WS_NORTH_STAR_RESEARCH_DWH_SSH_PRIVATE_KEY_FILE=/run/secrets/north-star-research-dwh-tunnel-key
THT_WS_NORTH_STAR_RESEARCH_DWH_SSH_KNOWN_HOSTS_FILE=/run/secrets/north-star-research-dwh-known-hosts
THT_WS_NORTH_STAR_RESEARCH_DWH_SSH_TARGET_HOST=dwh.internal.example
THT_WS_NORTH_STAR_RESEARCH_DWH_SSH_TARGET_PORT=5432
```
REST diagnostics reject a private per-request CA rather than weakening TLS; use runtime-trusted
HTTPS or verified direct/SSH native TLS. See the
[diagnostic protocol](../workspace-diagnostic-protocol.md).
An SSH connector can prove installation reachability, host-key verification, authentication, and
target identity, but it intentionally returns `workspace_not_activatable`; select direct or REST
before creating sessions. Git pull/push over SSH remains fully supported and is independent.
## Bootstrap, first pull, and diagnostics
Use the repository's canonical `compose.yaml` plus `deploy/compose.local.yaml`; they always start
`frontend`, `core`, `qdrant`, `embedding`, and the one-shot `embedding-model-init`. This profile
is CPU-first. Add `THOTH_ENABLE_EMBEDDING_GPU=1` only on a Linux host that intentionally exposes a
supported GPU device to Docker. Qdrant is a derived but persistent index, while Ollama keeps a
local model cache for `qwen3-embedding:0.6b` (`1024` dimensions, cosine distance). Do not copy or
maintain a standalone application Compose file. Copy [the bindings env example](examples/workspace-bindings.env.example) into an
untracked operator directory and create a protected operator env file from
`deploy/env/local.env.example`. It must contain absolute `PI_AUTH_FILE`,
`THT_SECRETS_FILE`, `THT_WORKSPACE_BINDINGS_ENV_FILE`, and connector `*_SOURCE` paths.
The Pi auth JSON, runtime secret bundle, and each connector credential remain separate protected
host files and are mounted read-only; their contents never enter the operator env or rendered
Compose.
Select exactly one repository Git transport override, `deploy/compose.git-ssh.yaml` or
`deploy/compose.git-https.yaml`. A Compose env file is not a shell environment, so export only the
non-secret paths required by the maintenance commands. Generate the connector override and render
through the preflight wrapper, which rejects unsafe paths and combined SSH+HTTPS selection.
Record the selected Git and generated connector overrides in the operator
[`thothii-installation.yaml` example](examples/thothii-installation.local.yaml), using absolute
paths, so `thothctl` remains the ordinary lifecycle interface.
```sh
export THT_SOURCE_ROOT=/absolute/path/to/ThothII
export THT_OPERATOR_ENV=/absolute/path/to/operator/local.env
export THT_WORKSPACE_BINDINGS_ENV_FILE=/absolute/path/to/operator/workspace-bindings.env
export THT_CONNECTOR_OVERRIDE=/absolute/path/to/operator/connector-secrets.local.yaml
"$THT_SOURCE_ROOT/scripts/generate-connector-secrets-override.sh" --bindings-env "$THT_WORKSPACE_BINDINGS_ENV_FILE" --operator-env "$THT_OPERATOR_ENV" --output "$THT_CONNECTOR_OVERRIDE"
"$THT_SOURCE_ROOT/scripts/compose-with-preflight.sh" --env-file "$THT_OPERATOR_ENV" \
-f "$THT_SOURCE_ROOT/compose.yaml" -f "$THT_SOURCE_ROOT/deploy/compose.local.yaml" \
-f "$THT_SOURCE_ROOT/deploy/compose.git-ssh.yaml" -f "$THT_CONNECTOR_OVERRIDE" config --quiet
```
```sh
"$THT_SOURCE_ROOT/scripts/compose-with-preflight.sh" --env-file "$THT_OPERATOR_ENV" \
-f "$THT_SOURCE_ROOT/compose.yaml" -f "$THT_SOURCE_ROOT/deploy/compose.local.yaml" \
-f "$THT_SOURCE_ROOT/deploy/compose.git-ssh.yaml" -f "$THT_CONNECTOR_OVERRIDE" up --build -d
curl --fail --silent http://127.0.0.1:8787/health
curl --fail --silent http://127.0.0.1:8787/workspace-registry/status
curl --fail --silent http://127.0.0.1:8787/workspaces
```
The first status request clones the registry, validates `thoth-workspaces.yaml`, every
catalog-listed descriptor, and any declared `<id>/evidence` tree, then atomically activates a
snapshot. A catalog-only slot with no descriptor reports `configuration_required` and is not
activatable. Use `POST /workspace-registry/pull` to fetch later curator revisions. Existing
curated descriptors stay read-only in the UI; only a missing descriptor may use the one-time
bootstrap create flow. Run workspace diagnostics only after required DWH bindings are mounted.
Schema-v3 diagnostics probe the internal Qdrant/Ollama services through backend config; ordinary
diagnostics are read-only.
<!-- workspace-descriptor-contract:start -->
Schema v3 is the only accepted workspace descriptor. Schema v1 and v2 workspace descriptors are
rejected before activation. Candidate snapshot validation makes bootstrap activation or a pull fail
atomically and leaves the prior active snapshot unchanged. There is no in-product migrator or
automatic conversion. The repository must already contain reviewed v3 descriptors. One workspace
owns one Qdrant collection; schema, Evidence, and Memory records share that collection and remain
isolated by payload `kind`.
<!-- workspace-descriptor-contract:end -->
| DWH | External | Configure the external endpoint and complete its runtime credentials in Workspace management. |
| LLM | External | Configure the external endpoint and model policy during installation. |
| Qdrant | Internal | Compose runs the internal service and persists `qdrant-data`. |
| Ollama embedding | Internal | Compose runs the internal `qwen3-embedding:0.6b` service and model-init job. |
## Semantic index ownership contract
| Scope | Ownership rule | Isolation rule |
| --- | --- | --- |
| Workspace semantic index | Each workspace reserves a single Qdrant collection. | Schema, Evidence, and Memory stay in that one collection and remain isolated by payload `kind`. |
| Workspace semantic index | Each workspace keeps exactly one Qdrant collection reserved for itself. | Schema, Evidence, and memory records share that one collection and are separated by the `kind` payload. |
If source material needs conversion, perform it outside ThothII in a separate reviewed process.
Commit only the resulting reviewed v3 descriptors. That external process must not import `${ENV}`
values, secret values, certificates, keys, or secret files into the repository.
The mandatory semantic stack is CPU-first. Set `THOTH_ENABLE_EMBEDDING_GPU=1` only after the
documented GPU prerequisites are satisfied. The embedding contract is fixed at
`qwen3-embedding:0.6b`, 1024 dimensions, cosine distance.
## Publish, update, backup, outage recovery, and rollback
## Prerequisites
Existing curated workspaces are read-only in the browser. Use the Workspace
Management page to pull, inspect status, validate a workspace, test it on this installation, and
optionally create one bootstrap descriptor for a pulled `configuration_required` slot. After that
first descriptor exists, change it only through curator Git commit/push and installation pull;
never hand-edit the running `repo/` volume. Before upgrading, record registry status, stop Compose,
and take a timestamped ownership-preserving backup of both registry and local data volumes while
excluding `installation-secrets/`. Render Compose, rebuild, start, and check status before
resuming work. If you are upgrading an older P1 registry, apply the reviewed migration in
[`docs/migrations/p1-to-p1-1-registry-layout.md`](../migrations/p1-to-p1-1-registry-layout.md)
and upgrade ThothII only after that commit is pushed.
- A working local installation described by [local.md](local.md).
- A remote Git repository and a read-only deploy credential for this ThothII installation.
- A separate authoring clone in which a workspace curator can edit and publish source revisions.
- `thothctl` built with `bash scripts/build-thothctl.sh`.
After a valid bootstrap, remote outage retains the last valid snapshot and reports `degraded: true`.
Pinned sessions continue. Repair network/authentication, pull, and confirm non-degraded status. To
undo a bad remote change, create a reviewed Git revert/release branch, advance the remote through
normal policy, pull, and confirm its new snapshot. Do not delete `snapshots/` as rollback.
## Prepare and publish a workspace source
Create a local workspace in an ordinary source directory outside ThothII's data directories. The
canonical repository layout is:
```text
thoth-workspaces.yaml
<workspace-id>/workspace.yaml
<workspace-id>/evidence/ # optional, repository-owned Evidence
<workspace-id>/schema/annotations.yaml # optional curated annotations
```
The catalog lists `{id, name, description?}` and the descriptor at
`<workspace-id>/workspace.yaml` must match that metadata. Use the examples in
`deploy/workspaces/` as authoring references. Do not store passwords, tokens, private keys, or
signed URLs in Git.
Publishing is an author-side Git operation: validate the source, commit it, and push it from the
separate authoring clone to the configured branch. This is the only meaning of “publish” in the
workspace lifecycle. ThothII has no author identity and no Git write credential.
<!-- workspace-descriptor-contract:start -->
Schema v3 is the only accepted workspace descriptor.
Schema v1 and v2 workspace descriptors are rejected before activation.
<!-- workspace-descriptor-contract:end -->
## Configure the remote Git repository
Copy `docs/install/examples/thothii-installation.local.yaml` to an operator-controlled absolute
path. Its `workspaceRepository` block records the remote, branch, and read-only access method.
Choose exactly one transport override:
- SSH: `deploy/compose.git-ssh.yaml`, with a read-only deploy key and pinned `known_hosts` file.
- HTTPS: `deploy/compose.git-https.yaml`, with a read-only token in a Git credentials file and an
optional private CA file.
The remote and branch are installation configuration. Git credentials remain protected
installation files and are never accepted by Workspace management or returned by its API.
Example non-secret/operator paths:
```dotenv
THT_WORKSPACE_GIT_REMOTE=git@git.example.com:organization/workspaces.git
THT_WORKSPACE_GIT_BRANCH=main
THT_WORKSPACE_INSTALLATION_ID=local
PI_AUTH_FILE=/absolute/path/to/operator/pi-auth.json
THT_SECRETS_FILE=/absolute/path/to/operator/thothii.secrets
THT_WORKSPACE_GIT_SSH_KEY_FILE=/absolute/path/to/operator/git-ssh-key
THT_WORKSPACE_GIT_KNOWN_HOSTS_FILE=/absolute/path/to/operator/git-known-hosts
```
Keep these files outside both the ThothII checkout and the workspace source repository. Protect
them with mode `0600` on macOS/Linux or an equivalent single-user ACL on Windows.
## Start and update the installation
Use only the installation-aware lifecycle:
```bash
export THT_SOURCE_ROOT=/absolute/path/to/ThothII
THTCTL="$THT_SOURCE_ROOT/tools/thothctl/thothctl"
INSTALLATION=/absolute/path/to/operator/thothii-installation.yaml
"$THTCTL" --installation "$INSTALLATION" start
"$THTCTL" --installation "$INSTALLATION" doctor
```
At startup ThothII clones or fetches the configured repository into its application-managed
`workspace-registry` volume. Later, **Update workspace repository** performs a server-side fetch
and fast-forward candidate checkout. It does not copy anything to the user's computer.
## Complete runtime secrets in Workspace management
Open Workspace management after the first successful repository update.
1. At the repository level, review the configured host, repository, branch, and current revision.
2. Select a workspace. Repository update does not require a selection; validation and connection
tests do.
3. Review the runtime fields derived from the selected DWH transport and Evidence authentication
mechanism.
4. Enter or rotate the required values and choose **Save runtime secrets**.
5. Run **Validate workspace** and then **Test connections**.
Secret fields are write-only. The GUI receives only configured/missing status. Values are
encrypted by the backend in the platform-neutral `workspace-secrets` volume. ThothII temporarily
materializes a restrictive file only while an existing file-oriented connector needs it, then
removes that file when the runtime lease ends. **Forget** deletes the selected encrypted value.
The workspace YAML stays environment-independent: it declares connector mechanisms, not host
paths or credentials. Installation trust material such as a Git CA or `known_hosts` remains an
operator concern; DWH and Evidence credentials are completed in the GUI.
## Validation and activation behavior
An update follows this sequence:
1. Fetch the configured branch into a candidate checkout managed by ThothII.
2. Validate the catalog, every descriptor, repository-relative Evidence, and cross-workspace
invariants at the same Git commit.
3. If every workspace is valid, atomically mark that complete commit as active.
4. If any validation fails, report sanitized diagnostics and keep the previous active revision.
The active checkout is read-only application state. Never edit files under
`/data/workspace-registry`. A source correction must be committed and pushed from the authoring
clone, then fetched again with **Update workspace repository**.
## Backup, rotation, and recovery
Back up the `workspace-registry`, `workspace-secrets`, `sessions`, `qdrant-data`,
`embedding-models`, `settings`, and `pi-state` volumes together. The encrypted vault is useless
without its generated master key, so preserve the entire `workspace-secrets` volume and protect
the backup as secret material.
Rotate a runtime credential by saving its replacement in Workspace management and rerunning its
connection test. Rotate Git credentials in the installation files and restart `core`. To recover
from a bad remote revision, correct or revert it in the authoring repository and run the update;
until validation succeeds, the previous active snapshot remains available.
## Troubleshooting
| Stable code | Meaning and safe action |
| Symptom | Meaning and action |
| --- | --- |
| `workspace_invalid` | Invalid descriptor/path/snapshot; restore a reviewed canonical revision. |
| `binding_missing` | A selected value or readable `*_FILE` is absent; fix the local binding/mount. |
| `workspace_not_activatable` | Diagnostics cannot activate the workspace; correct the selected transport. |
| `workspace_stale` | Checkout changed or is busy; stop competing pull or sync work. |
| `workspace_conflict` | Draft base differs from Git; pull, resolve the diff, validate, and retry after the curator pull/bootstrap flow. |
| `git_unavailable` | Remote, path, network, or lock unavailable; preserve the degraded valid snapshot. |
| `git_auth_failed` | Mounted SSH/HTTPS material rejected/unreadable; rotate or fix permissions without logging it. |
| `git_non_fast_forward` | Checkout diverged; reconcile through the registry workflow. |
| `git_push_rejected` | Remote policy rejected the change; review branch protection/hooks. |
| `connector_unavailable` | DNS/TLS/auth/resource identity diagnostic failed; inspect local bindings and egress. |
| `semantic_index_incompatible` | Collection/model/dimensions/distance differs from Git; perform an explicit index migration. |
On macOS, restart Docker Desktop if a named volume disappears. On Windows, check WSL2 and Docker
file sharing. A failed first bootstrap has no snapshot fallback: repair remote trust and retry;
never create an unreviewed local registry repository.
| Repository unavailable | Check remote host, branch, read-only deploy credential, CA, and `known_hosts`. |
| Candidate rejected | Fix the reported source error in the authoring clone, commit, push, and update again. |
| Runtime configuration required | Select the workspace and complete each required secret field. |
| Connection test fails | Rotate the relevant secret or correct the non-secret endpoint in the source/installation as appropriate. |
| Active revision did not change | The candidate was invalid or was already active; inspect the repository status. |