docs: add autonomous local installation guide

2026-08-05 08:35:13 +02:00
parent c01202f06c
commit 53d257fb76
7 changed files with 779 additions and 0 deletions
@@ -0,0 +1,80 @@
+# Windows and WSL2 line endings
+
+ThothII's containers execute shell scripts from the source checkout. Those files must stay LF,
+even when the PC normally uses CRLF. The repository's `.gitattributes` is authoritative, but a
+Windows Git setting or an old checkout can still leave incorrect bytes. Check line endings after
+every clone and pull, before building an image.
+
+## Recommended WSL2 clone
+
+Use Docker Desktop with WSL2 integration. Clone inside the Linux filesystem, for example under
+`/home/<user>/src`, rather than under `/mnt/c`. This avoids slow cross-filesystem builds,
+permission surprises, and Windows tools rewriting files behind WSL.
+
+```sh
+mkdir -p "$HOME/src"
+cd "$HOME/src"
+git -c core.autocrlf=false clone https://github.example.invalid/your-org/ThothII.git
+cd ThothII
+git config --local core.autocrlf false
+bash scripts/verify-line-endings.sh
+```
+
+Keep Docker Desktop's integration enabled for that WSL distribution. Run the Linux build scripts
+and the Linux `thothctl` binary from the same WSL shell.
+
+## Repository-local LF policy
+
+Set the option in this repository only. Do not change a company-wide or personal Git policy just
+for ThothII.
+
+```sh
+git config --local core.autocrlf false
+git config --local --get core.autocrlf
+```
+
+The second command must print `false`. `.gitattributes` keeps shell, YAML, Dockerfile, JSON,
+TypeScript, Python, and Markdown files at LF; PowerShell files remain CRLF.
+
+For a native PowerShell clone, disable conversion during the first checkout and then store the
+repository-local setting:
+
+```powershell
+git -c core.autocrlf=false clone https://github.example.invalid/your-org/ThothII.git
+Set-Location ThothII
+git config --local core.autocrlf false
+& "C:\Program Files\Git\bin\bash.exe" scripts/verify-line-endings.sh
+```
+
+## Verify after clone or pull
+
+From WSL2, Git Bash, macOS, or Linux run:
+
+```sh
+bash scripts/verify-line-endings.sh
+```
+
+Success exits with code 0 and prints no offending path. If it lists a file, do not build or start
+ThothII. Correct the checkout first. Native PowerShell users can invoke the same script through
+Git for Windows as shown above.
+
+## Recover an existing CRLF clone
+
+The safest recovery is to reclone into a new directory. First commit wanted work or copy it to a
+backup outside both clones. Then clone with conversion disabled, run the verifier, and copy back
+only reviewed changes.
+
+If a reviewed working tree must be repaired in place, make a backup or commit all wanted changes
+before continuing. Then use Git's repository attributes to stage a renormalization:
+
+```sh
+git status --short
+git config --local core.autocrlf false
+git add --renormalize .
+git diff --cached --check
+git diff --cached
+bash scripts/verify-line-endings.sh
+```
+
+Review every staged change before committing. The procedure intentionally avoids destructive Git
+resets; replacing the clone is easier to audit and much safer for uncommitted work.