nightshift: doc-drift analysis

[nightshift-micr]

Nightshift: Doc-Drift Analysis

Summary

Documentation drift analysis comparing docs/, README.md, and CONTRIBUTING.md against the actual code in internal/ and cmd/.

Findings

🔴 Missing CLI flags in README run flags table

The run command in internal/app/cli.go defines these flags that are not listed in the README's run flags table (lines 62–76):

Flag	Default	Description	Source
--log	platform default	Log file path	cli.go:57
--dry-run	false	Print commands without executing	cli.go:58

Severity: Medium — operators reading the README won't discover --log and --dry-run without reading source.

🟡 Missing agent flags in README command surface

The README documents agent with --once but omits other agent flags from cli.go:105-114:

Flag	Default	Description
--interval	1m	Reconciliation interval
--config	(inherited)	Config path
--state	(inherited)	State path
--audit	(inherited)	Audit path
--log	(inherited)	Log path
--dry-run	(inherited)	Dry-run mode

Severity: Low — --interval is especially useful for tuning agent behavior and should be documented.

🟡 Stale link in docs/configuration.md

Line 5 references a local filesystem path instead of a GitHub-relative path:

Example: [configs/tailstick.config.example.json](/home/ubuntu/workspace/tailscale-usb/configs/tailstick.config.example.json)

Should be:

Example: [configs/tailstick.config.example.json](../configs/tailstick.config.example.json)

Severity: Medium — link is broken in rendered GitHub markdown.

🟢 Architecture doc is accurate

docs/architecture.md correctly lists all 8 internal packages matching the actual code structure:

• internal/app, internal/gui, internal/config, internal/state, internal/tailscale, internal/platform, internal/crypto, internal/logging ✅

🟢 CONTRIBUTING.md package table is accurate

All packages listed in the CONTRIBUTING.md architecture table match actual code. ✅

🟢 Operations guide is accurate

docs/operations.md correctly describes enrollment flow, agent reconciliation, and state/log paths. ✅

Recommendations

1. Add --log and --dry-run to README run flags table — these are user-facing flags operators need.
2. Add an agent flags section to README — document --interval, --once, --config, --state, --log, --dry-run, --audit.
3. Fix broken link in docs/configuration.md line 5 — change absolute local path to relative GitHub path.

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