# Local workspace repository installation (macOS, Windows, and Linux)

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 | 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 keeps exactly one Qdrant collection reserved for itself. | Schema, Evidence, and memory records share that one collection and are separated by the `kind` payload. |

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.

## Prerequisites

- 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.
- `tht` built with `bash scripts/build-tht.sh`.

## 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.

## Use the workspace from the application

After the installation is started, use Workspace management from the authenticated application:

1. Run **Update workspace repository** to fetch and validate the configured Git branch into the
   application-owned registry. The operation is all-or-nothing and does not modify the authoring
   clone.
2. Confirm that the installation-owned `workspace-secrets` storage remains outside the source
   repository and contains no credentials in the workspace descriptors.
3. Select the workspace and run **Validate workspace source** to verify the active descriptor, catalog,
   Evidence, annotations, and runtime bindings.
4. Run **Test workspace connections** only with the approved read-only DWH/Evidence test configuration.
   Results are redacted and the workspace source remains unchanged.

<!-- 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
THT_BIN=tht
INSTALLATION=/absolute/path/to/operator/thothii-installation.yaml
"$THT_BIN" --installation "$INSTALLATION" start
"$THT_BIN" --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

### Chiavi DWH REST per installazione

Se il binding selezionato è `rest_api`, la chiave DWH è una credenziale per questa installazione e si salva nel vault tramite **Save entered secrets** oppure in un file locale indicato da `API_KEY_FILE`. `postgres_direct` e `ssh_tunnel` non usano questa chiave. Per emissione, TLS, rotazione e verifica `/rpc/ping`, seguire [enrollment DWH REST](dwh-auth-client-enrollment.md).

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 entered secrets**.
5. Run **Validate workspace source** and then **Test workspace 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 stored value** 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

| Symptom | Meaning and action |
| --- | --- |
| 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. |