feat(cli): prepare and validate workspace documents offline

Reuse the runtime catalog and workspace parsers in a standalone helper paired with tht. Add document templates, safe diagnostics, local Evidence checks, native bundle builds, shared CLI fixtures and IT/EN preparation guides. Record the approved document-first specification and ticket breakdown. Refs #43.
2026-09-28 15:35:25 +02:00
parent 67ee52624c
commit 64e6b9664a
20 changed files with 2195 additions and 4 deletions
@@ -7,6 +7,63 @@ question, queries an enterprise database read-only, and guides the user through
 core, PostgreSQL catalog, Qdrant, embedding service, and Pi run in Docker; Node.js, Python, and Pi
 are not required on the host.

+## Prepare and validate workspace documents before starting the stack
+
+The first two steps of the new flow work without Docker, Node, Python, Pi or an
+installation descriptor. Use the platform bundle with **both** `tht` and
+`tht-workspace-documents` in the same directory (`.exe` on Windows). Put that directory
+on `PATH`, or invoke the absolute executable path. Older packages containing only
+`tht` do not provide this capability. Maintainers can currently build the bundle;
+publishing assets and Docker Hub images belongs to a later delivery step. The rest
+of this guide still describes the existing installation path.
+
+1. Choose a new directory outside the application checkout, with an existing parent:
+
+   ```sh
+   tht workspace prepare --directory ./my-workspaces --id practice --name "Practice" --language en
+   ```
+
+   This creates `thoth-workspaces.yaml`, `practice/workspace.yaml` and
+   `workspace-docs/practice/README.md`. Existing destinations, even empty ones, are
+   refused. No services start, Git is not initialized and no remote is contacted.
+   Example databases remain a deferred subproject. For a curator-supplied repository,
+   use a separate local copy and go straight to step 3; read access to the origin is
+   sufficient.
+2. Edit the catalog (schema v1) and workspace descriptor (schema v4) at your own pace.
+   Keep `id`, `name` and optional `description` identical in both; the id must match
+   the directory name. Root directories must match catalog entries, except
+   `workspace-docs` and the local `.git` directory. Database connections, schema and
+   credentials belong to the installation Metadata Catalog. Evidence is optional
+   and initially absent.
+3. Validate, correct the reported document/field, and repeat:
+
+   ```sh
+   tht workspace validate --directory ./my-workspaces
+   tht workspace validate --directory ./my-workspaces --json
+   ```
+
+   PowerShell uses the same arguments, for example
+   `C:\ThothII\bin\tht.exe workspace validate --directory C:\ThothII\my-workspaces`.
+   Validation changes no files. It rejects multiple/malformed YAML documents,
+   duplicate keys/ids, unknown fields, catalog/directory/descriptor mismatches,
+   missing local references and symbolic links. Fix the first error in each document
+   and repeat to reveal any subsequent errors.
+
+Evidence `absent` is valid. Filesystem checks cover directories, accessibility and
+literal references; standard Markdown selections also check declared size limits.
+Evidence v2 requires `curated/` and syntactically valid YAML frontmatter. Local limits
+are 1 MiB per document read and 100,000 entries per Evidence tree. Arbitrary patterns,
+the complete curated-unit contract, provenance, HTTP/S3 access and indexing remain
+explicit runtime checks. See the [Evidence guide](../evidence.md).
+
+JSON includes `schema_version`, `scope: local-documents`, `ok`, `workspaces`, `issues`
+and `deferred_checks`. Issues identify document, field, code, correction and YAML
+line where available, without printing document values. Exit statuses: `0` local
+success, `1` documents/access/bundle need correction, `2` invalid arguments. Local
+success does not certify semantic truth, connectivity or readiness. The Git revision
+activated later must contain the checked documents; this command does not publish
+uncommitted files or empty directories.
+
 ## Before you start: the two repositories

 There are two separate repositories: