Proposal: canonical top-level locations field

[paulbennun]

Summary

Opens discussion on promoting locations from a producer-namespaced extension (we currently carry it as x-nm-locations) to a canonical top-level NCP field. Four-field shape: id, name, description?, environment_hints?.

Full proposal: docs/proposals/2026-04-24-locations.md.

This PR adds only the proposal document — it does not change schema/ or examples/. It is intentionally left as a draft to open discussion; if the direction is agreeable, a follow-up PR would add the schema + fixtures per CONTRIBUTING.

What's in the proposal

• Motivation. 18 months of adopter experience emitting/consuming a locations array; a working 6-location corpus; and a downstream pattern (scene-level location_id FKs) that benefits from a canonical home for the list.
• Proposed schema. Optional top-level locations: [] with {id, name, description?, environment_hints?} — two required, two optional. environment_hints specified as producer-defined free-form tags (no closed vocabulary at the canonical level).
• Backward compatibility. Additive; optional; closed-root additionalProperties: false preserved by updating the root allow-list. Absent producers and absent consumers behave unchanged.
• Out of scope explicitly. Per-beat presence graphs, scene-level FK definition, acoustic routing semantics, and adjacency/navigation graphs are all kept to the producer/consumer side.
• Reference implementation. paulbennun/NCPKit has been running this shape for about 18 months (currently serialised as x-nm-locations under 2.1.0).

What this PR is not

• Not a schema change. schema/ncp-schema.yaml / schema/ncp-schema.json are untouched.
• Not urgent. We carry x-nm-locations happily and will continue to; this is a good-citizen proposal rather than a blocker for anything.
• Not prescriptive on form — happy to restructure as a GitHub Issue first, or split into proposal + schema PR, per the maintainers' preferred workflow.

Test plan

• Proposal document renders correctly on GitHub
• Maintainers read and advise on preferred workflow (issue first? direct schema PR?)
• If direction is agreed, follow up with schema PR per CONTRIBUTING.md (schema + examples + npm run validate:schema)

[jhull]

Paul, thank you for the great idea and the detailed proposal. The core point makes total sense: NCP should not require repeating the same place/setting details across Moments when several Moments share the same Setting. We accepted the concept using NCP terminology as story-level settings[] plus optional moment.setting_id, while preserving free-text moment.setting for lightweight cases. That schema/docs/example change is now merged in #13. Really appreciate you surfacing this and helping tighten the protocol shape.