Decide the fate of the skyhook-named on-host paths before v1 freeze (/skyhook-package, /var/lib/skyhook, /var/log/skyhook, /etc/skyhook)

[lockwobr]

Summary

Decide what happens to the skyhook-named on-host and in-container paths before the v1 API freeze. These are part of the package contract, so this is a compatibility decision first and a rename second.

Part of the rename tracked in #310. Related: #436 (namespace), #438 (SKYHOOK_* env vars).

The paths

Path	Purpose	Defined at
/skyhook-package	Package payload root, contains config.json	agent/skyhook-agent/src/skyhook_agent/controller.py:68 (SKYHOOK_DATA_DIR default)
/skyhook-package/configmaps	ConfigMap mount point	operator/internal/controller/skyhook_controller.go:87
/skyhook-package/node-metadata	Node metadata mount	operator/internal/controller/skyhook_controller.go:2614
/etc/skyhook	Agent root dir	agent/skyhook-agent/src/skyhook_agent/controller.py:70 (SKYHOOK_ROOT_DIR default)
/var/log/skyhook	Agent log root	controller.py:72, and AgentLogRoot default at skyhook_controller.go:121
/var/lib/skyhook	Copy dir root	CopyDirRoot default at skyhook_controller.go:116

Roughly 90 references across the operator, agent, chart, packages, and docs.

Why this is not a mechanical rename

Every package image ever built reads /skyhook-package/config.json. That includes the packages in NVIDIA/nodewright-packages and every package any user has written. Changing the path breaks all of them at once, with no version negotiation, because the path is baked into package step scripts rather than passed in.

/var/lib/skyhook and /var/log/skyhook are also persistent on-host state. Renaming them without a migration strands existing flag files and logs on every node in every cluster, which at minimum means packages re-run work they already did.

Options

1. Never rename. Accept the paths as a historical wart, document them as stable API. Cheapest, and defensible: /skyhook-package is a contract identifier, not branding.
2. Dual-read with a deprecation window. Agent prefers /nodewright-package, falls back to /skyhook-package; operator mounts both, or symlinks. Persistent dirs get a one-shot migration in the agent.
3. Rename at the v1 boundary as a documented breaking change, with a package-side migration guide.

The Go agent rewrite is the natural place to implement option 2 if we want it, since the path handling is being written fresh anyway.

Why it needs a decision now

docs/versioning.md enforces semver strictly and v1 is meant to freeze the package contract. If these paths are part of that contract, the decision belongs before the freeze, not after. "We never decided" becomes "we shipped it as stable" by default.

Acceptance criteria

• Decision recorded (rename / dual-read / never), with rationale, in a design doc under docs/designs/
• If not renaming: the paths are explicitly documented as stable contract surface in docs/ so this does not get re-litigated
• If renaming: migration path for existing on-host state, and a compatibility window for existing package images
• agent/README.md and the package authoring docs reflect the outcome