From 460caa550cb86d2e5a79b35558994e3a490437c6 Mon Sep 17 00:00:00 2001
From: mptyl <mp@tylconsulting.it>
Date: Sat, 15 Aug 2026 21:25:48 +0200
Subject: [PATCH] docs: clarify workspace authoring guidance

---
 frontend/src/shell/WorkspaceManager.test.tsx |  7 ++++++-
 frontend/src/shell/WorkspaceManager.tsx      | 10 ++++++++--
 2 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/frontend/src/shell/WorkspaceManager.test.tsx b/frontend/src/shell/WorkspaceManager.test.tsx
index 40c87bdf..05942e35 100644
--- a/frontend/src/shell/WorkspaceManager.test.tsx
+++ b/frontend/src/shell/WorkspaceManager.test.tsx
@@ -92,7 +92,7 @@ test("offers a button above the workspace list that returns to Level 1", async (
   expect(await screen.findByRole("heading", { name: "Workspace-specific actions" })).toBeVisible();
 
   const navigation = screen.getByRole("navigation", { name: "Workspaces" });
-  const backButton = within(navigation).getByRole("button", { name: "Back to main page" });
+  const backButton = within(navigation).getByRole("button", { name: "Back to Level 1" });
   expect(backButton).toHaveClass("border-border", "bg-card", "w-full");
   expect(backButton.compareDocumentPosition(within(navigation).getByText("Available workspaces"))
     & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
@@ -114,6 +114,11 @@ test("level one explains the read-only Git sequence and the repository update bu
   const overview = screen.getByTestId("workspace-overview");
   expect(within(overview).getByText(/Git server such as GitHub, GitLab, or Gitea/i)).toBeVisible();
   expect(within(overview).getByText(/configured during ThothII installation/i)).toBeVisible();
+  expect(within(overview).getAllByRole("listitem")[0]).toHaveTextContent(/choosing any local directory you prefer/i);
+  expect(within(overview).getByRole("link", { name: /workspace authoring instructions on GitHub/i })).toHaveAttribute(
+    "href",
+    "https://github.com/mptyl/ThothII/blob/main/docs/install/local-workspace-registry.md#prepare-and-publish-a-workspace-source",
+  );
   expect(within(overview).getAllByText(/managed read-only checkout/i)).toHaveLength(2);
   expect(within(overview).getByText(/current active revision remains unchanged/i)).toBeVisible();
   expect(within(overview).getByText(/No workspace selection is required/i)).toBeVisible();
diff --git a/frontend/src/shell/WorkspaceManager.tsx b/frontend/src/shell/WorkspaceManager.tsx
index 234edecb..afc01b0f 100644
--- a/frontend/src/shell/WorkspaceManager.tsx
+++ b/frontend/src/shell/WorkspaceManager.tsx
@@ -57,6 +57,9 @@ function stateLabel(state: "ready" | "configuration_required"): string {
   return state === "ready" ? "Ready" : "Runtime configuration required";
 }
 
+const workspaceAuthoringGuideUrl =
+  "https://github.com/mptyl/ThothII/blob/main/docs/install/local-workspace-registry.md#prepare-and-publish-a-workspace-source";
+
 export function WorkspaceManager({ open, onClose }: { open: boolean; onClose: () => void }) {
   const queryClient = useQueryClient();
   const [selectedId, setSelectedId] = useState<string>();
@@ -242,7 +245,7 @@ export function WorkspaceManager({ open, onClose }: { open: boolean; onClose: ()
               className="mb-3 w-full justify-start"
               onClick={showLevelOne}
             >
-              <ArrowLeft />Back to main page
+              <ArrowLeft />Back to Level 1
             </Button>
             <p className="mb-2 px-2 text-xs font-semibold uppercase tracking-wide text-muted-foreground">Available workspaces</p>
             <div className="min-h-0 flex-1 overflow-y-auto">
@@ -290,11 +293,14 @@ export function WorkspaceManager({ open, onClose }: { open: boolean; onClose: ()
                   <h2 className="font-heading text-xl font-semibold">How workspaces reach ThothII</h2>
                 </div>
                 <ol className="grid list-decimal gap-3 pl-5 text-sm leading-6 text-muted-foreground">
-                  <li><span className="font-medium text-foreground">Create a local workspace</span> in its own source directory. It must contain <code>workspace.yaml</code> and every required subdirectory, including any versioned Evidence files.</li>
+                  <li><span className="font-medium text-foreground">Create a local workspace</span> by choosing any local directory you prefer and setting up the workspace there. It must contain <code>workspace.yaml</code> and every required subdirectory, including any versioned Evidence files.</li>
                   <li>Publish that source by committing and pushing it to a repository hosted by a Git server such as GitHub, GitLab, or Gitea.</li>
                   <li>The repository address, branch, and read-only Git credentials are configured during ThothII installation. This installation reads <span className="font-medium text-foreground">{repositoryLabel}</span> on branch <span className="font-mono text-foreground">{statusQuery.data?.branch ?? "main"}</span>.</li>
                   <li>ThothII fetches the configured branch into its managed read-only checkout, validates the complete candidate revision, and activates it only when validation succeeds. It never edits, commits, pushes, or publishes workspace source.</li>
                 </ol>
+                <p className="text-sm leading-6 text-muted-foreground">
+                  Follow the <a href={workspaceAuthoringGuideUrl} target="_blank" rel="noreferrer" className="font-medium text-foreground underline underline-offset-4 hover:text-primary">workspace authoring instructions on GitHub</a> for the required layout and validation rules.
+                </p>
                 <div className="rounded-lg border border-border bg-muted/30 p-4">
                   <div className="flex flex-wrap items-start justify-between gap-4">
                     <div className="max-w-2xl">