[nightshift] doc-drift: 13 documentation-code discrepancies found

[nightshift-micr]

Summary

Documentation drift analysis comparing all docs (README.md, docs/*.md) against the actual source code. Found 13 issues ranging from broken links to outdated version references and missing documentation.

---

Findings

🔴 P0 — Critical / Broken User-Facing Paths

1. Broken example config link in docs/configuration.md

• File: docs/configuration.md line 5
• Issue: Link uses an absolute local filesystem path: /home/ubuntu/workspace/tailscale-usb/configs/tailstick.config.example.json
• Expected: Relative path: (../configs/tailstick.config.example.json)

---

🟠 P1 — Significant Inaccuracy

2. Go version mismatch in README.md

• File: README.md line 29
• Doc says: **go 1.22+** is required for building from source.
• Code says: go.mod line 3: go 1.25.6
• Fix: Update to **Go 1.25.6+**

3. --days flag constraint not documented

• File: README.md line 67
• Doc says: timed lease duration in days (implies any integer)
• Code says: internal/tailscale/client.go validates --days must be one of {1, 3, 7} when used without --custom-days
• Fix: Update description to: timed lease duration in days: 1, 3, or 7

---

🟡 P2 — Moderate Drift

4. Logger package doc claims "automatic rotation" — no rotation code exists

• File: internal/logging/logger.go line 2
• Doc says: "provides structured, file-based logging with automatic rotation"
• Reality: Logger simply appends to a single file. No rotation logic.

5. make build-all doesn't produce arm64 binaries locally

• File: README.md line 49, 183
• Doc says: release binaries for linux/amd64, linux/arm64, windows/amd64, windows/arm64
• Code says: Makefile build-all only compiles linux/amd64 and windows/amd64
• Fix: Either update Makefile or clarify README that arm64 requires CI release workflow

6. Module path mismatch

• README badges: github.com/Microck/tailstick
• go.mod: github.com/tailstick/tailstick
• Potentially intentional but could confuse contributors

7. Architecture docs don't mention platform.Runner/dry-run abstraction

• File: docs/architecture.md lines 27-33
• Missing documentation of the platform.Runner interface which is a key architectural feature enabling dry-run mode

8. GUI missing nonInteractive support

• File: internal/gui/server.go lines 33-43
• README documents --non-interactive as a run flag but GUI enrollRequest has no such field
• README should clarify this is CLI-only

---

🔵 P3 — Minor / Cosmetic

9. Inconsistent capitalization in README platform table

• Lines 44-47 use lowercase "linux"/"windows" vs title case elsewhere

10. Release runbook go build multi-package differs from make build convention

• File: docs/release-runbook.md line 25

11. Env expansion vs *Env fields interaction could be clearer

• File: docs/configuration.md lines 69-77

---

Recommended Priority Fixes

1. Fix broken link in docs/configuration.md line 5
2. Update Go version in README.md line 29
3. Clarify --days constraints in README
4. Fix Logger package doc — remove "automatic rotation" claim
5. Align make build-all with documented architectures or update README

Automated by Nightshift v3 (GLM 5.1)

[Microck]

Resolved by merged backlog sweep #43 plus prior docs updates already on main. The specific doc-drift items called out here are now covered and this generated audit is stale.