Decide the fate of the SKYHOOK_* environment variables before v1 freeze

[lockwobr]

Summary

Decide what happens to the 14 SKYHOOK_* environment variables before the v1 API freeze. Like the on-host paths, these are package-author contract surface, so this is a compatibility decision first and a rename second.

Part of the rename tracked in #310. Related: #436 (namespace), #437 (on-host paths).

The variables

Occurrence counts across *.go, *.py, *.yaml, *.md, *.sh (excluding vendor):

Variable	Refs	Notes
SKYHOOK_RESOURCE_ID	58	Gates interrupt re-runs; unique per package config
SKYHOOK_AGENT_WRITE_LOGS	37
SKYHOOK_NODE_ORDER	31	User-facing, documented in docs/ordering_of_skyhooks.md
SKYHOOK_DIR	17	Used in the operator's copy command, skyhook_controller.go:2690
SKYHOOK_ROOT_DIR	15	Defaults to /etc/skyhook
SKYHOOK_LOG_DIR	15	Defaults to /var/log/skyhook
SKYHOOK_DATA_DIR	14	Defaults to /skyhook-package
SKYHOOK_NAME	11
SKYHOOK_VAR	6
SKYHOOK_AGENT_BUFFER_LIMIT	3
SKYHOOK_YAML	2
SKYHOOK_COMPLETE_TIMEOUT	2
SKYHOOK_CONFIGMAP_DIR	1
SKYHOOK_AGENT_MODE	1

Why this is not a mechanical rename

These are read by package step scripts, not just by our own code. A package author writing a shell step reads $SKYHOOK_RESOURCE_ID or $SKYHOOK_DATA_DIR directly. Renaming the variable without dual-export silently changes behavior in user packages: the variable is simply unset, the script sees an empty string, and there is no error.

SKYHOOK_NODE_ORDER is additionally documented user-facing configuration.

Options

1. Never rename. Document as stable contract.
2. Dual-export. Agent exports both SKYHOOK_* and NODEWRIGHT_* for a deprecation window; new packages read the new names. This is cheap for env vars, much cheaper than the equivalent for paths (Decide the fate of the skyhook-named on-host paths before v1 freeze (/skyhook-package, /var/lib/skyhook, /var/log/skyhook, /etc/skyhook) #437), because exporting two names costs nothing at runtime.
3. Rename at v1 as a documented break.

Option 2 is meaningfully more attractive here than in #437, and the Go agent rewrite is the natural place to implement it.

Why it needs a decision now

v1 is meant to freeze the package contract. If these variables are part of it, decide before the freeze rather than inheriting them as stable by default.

Acceptance criteria

• Decision recorded (rename / dual-export / never), with rationale
• If dual-exporting: both names set by the agent, deprecation window defined, warning emitted when only the legacy name is consumed if that is detectable
• Outcome documented in agent/README.md and the package authoring docs
• docs/ordering_of_skyhooks.md updated if SKYHOOK_NODE_ORDER changes
• Decision is consistent with whatever Decide the fate of the skyhook-named on-host paths before v1 freeze (/skyhook-package, /var/lib/skyhook, /var/log/skyhook, /etc/skyhook) #437 concludes for paths, since SKYHOOK_DATA_DIR / SKYHOOK_ROOT_DIR / SKYHOOK_LOG_DIR are the defaults for those paths