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