ThothII/docs/plans/2026-08-19-tht-documentation-convergence.md

Tht Documentation Convergence Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Align current documentation and documentation smoke checks with the converged native host CLI tht, while preserving historical references only where they describe past decisions or evidence.

Architecture: Treat tools/tht/cmd/tht/main.go as the canonical host CLI surface for installation, authentication, diagnostics, lifecycle, and workspace operations. Keep the Python harness/.venv/bin/tht distinction explicit for the workflow runtime, and update current operator/test instructions to invoke the native tht with --installation.

Tech Stack: Markdown documentation, shell smoke tests, Go CLI command surface, repository search-based verification.

---

Task 1: Classify current and historical legacy CLI references

Files:

• Inspect: README.md, PROJECT_STATE.md, AGENTS.md, docs/**, scripts/**
• Reference: tools/tht/cmd/tht/main.go

Step 1: Build a complete occurrence inventory with a case-insensitive search for the former host CLI name and classify every match.

Step 2: Classify each occurrence as current operator documentation, documentation smoke expectation, executable/script contract, or historical design/evidence.

Step 3: Record the classification in the implementation notes before editing.

Task 2: Update canonical operator and installation documentation

Files:

• Modify: README.md
• Modify: AGENTS.md
• Modify: PROJECT_STATE.md
• Modify: docs/guida-utente.md
• Modify: docs/contracts/workspace-preprocessing-cli.md
• Rename/update: docs/contracts/tht-pi.md as the current tht Pi contract
• Modify: relevant installation and architecture pages that expose operator commands

Step 1: Replace current host/operator invocations with tht --installation ....

Step 2: Document the distinction between the native host CLI tht and the Python harness CLI invoked by the backend/runtime.

Step 3: Update command examples for start, status, doctor, auth, workspace, and pi.

Step 4: Add a short historical note only where a document must explain the former name.

Task 3: Rewrite authentication acceptance and manual test instructions

Files:

• Modify: docs/testing/authentication-manual-acceptance.md
• Modify: docs/plans/2026-08-18-thothii-authentication-acceptance-and-psd-deployment.md
• Modify: docs/install/authentication-local.md
• Modify: docs/install/authentication-oidc.md
• Modify: docs/install/authentik.md

Step 1: Make tht auth status, tht auth check, tht auth check --interactive, and tht doctor --json the canonical terminal preflight.

Step 2: Use tht status, tht start, and tht workspace inspect --workspace psd-clinical --json for PSD deployment checks.

Step 3: Clarify that the P8 L2 gate is authentication-to-application integration through the first reviewer gate.

Step 4: Retain the prior functional test suite as a baseline and add only the authentication boundary smoke required for this acceptance.

Task 4: Align documentation smoke tests

Files:

• Modify: scripts/auth-docs-smoke.sh
• Modify: scripts/test-auth-docs-smoke.sh
• Inspect/update: any current smoke script whose user-facing command examples still require the legacy CLI name

Step 1: Replace forbidden/current command assertions with tht equivalents.

Step 2: Preserve negative checks for obsolete authentication CLI wording.

Step 3: Run the positive and negative documentation fixtures.

Task 5: Preserve or annotate historical material

Files:

• Inspect the historical discovery specification for context, without treating it as current operator documentation.
• Inspect: dated reports and archived acceptance scripts

Step 1: Do not rewrite historical titles, commit evidence, or old implementation names solely to erase history.

Step 2: Add a concise “historical nomenclature” note where an archived document could otherwise be mistaken for current instructions.

Task 6: Verify the convergence

Step 1: Run scripts/auth-docs-smoke.sh and scripts/test-auth-docs-smoke.sh.

Step 2: Search active documentation for remaining legacy CLI references.

Step 3: Confirm every remaining match is either an explicit historical note, an ignored runtime directory name, or a non-document executable compatibility artifact.

Step 4: Run git diff --check and report the exact files changed plus any intentionally retained historical references.