`mass environment preview` ignores per-instance `remoteReferences` documented in the preview spec

[coryodaniel]

Summary

The preview environment docs show a remoteReferences list under each entry in instances. mass environment preview does not read that key. yaml.Unmarshal into PreviewConfig drops it with no error, so a config that follows the docs runs, forks the environment, and sets no remote references.

Docs spec

docs/workflows/03-preview-environments.md in massdriver-cloud/docs:

instances:
  chatsvc:
    remoteReferences:
      # UUID form
      - resourceId: a1b2c3d4-...
        field: kubernetes_cluster
      # Or another instance's output: <instance-id>.<field>
      - resourceId: demo-prod-db.hostname
        field: database

Current CLI

internal/commands/environment/preview.go:

type InstanceOverride struct {
    Version string          `json:"version,omitempty"`
    Params  map[string]any  `json:"params,omitempty"`
    Secrets []PreviewSecret `json:"secrets,omitempty"`
}

There is no RemoteReferences field. LoadPreviewConfig decodes with yaml.Unmarshal and does not reject unknown keys.

The only related option is the fork-wide copyRemoteReferences boolean. Its comment says the SDK does not expose a per-instance set operation. That is not true. mass instance remote-reference set in this same repo calls mdClient.Instances.SetRemoteReference.

Backend

The API supports this. The setRemoteReference mutation takes organizationId, instanceId, resourceId and input: { field }. resourceId accepts a UUID or <instance>.<field>. The instance must not be PROVISIONED or FAILED. Freshly forked instances meet that condition, so the order fork, set references, deploy works.

Reproduce

1. Write a preview.yaml with remoteReferences under an instance, per the docs.
2. Run mass environment preview x -f preview.yaml.
3. The command exits 0 and forks the environment. mass instance get <project>-x-<instance> shows no remote reference.

Expected

• Add RemoteReferences []PreviewRemoteReference (resourceId, field) to InstanceOverride.
• After the fork, call SetRemoteReference for each entry, in the same place per-instance secrets are applied.
• Decode the config with yaml.NewDecoder and KnownFields(true) so unknown keys fail instead of being dropped.
• Remove the stale comment on CopyRemoteReferences.
• Add a test that loads a config with per-instance remoteReferences and asserts each set call.