Maintain the feature map

feature-map.json at the repo root is the product's public information architecture: the top-level categories (the features array; count them in the file, not here), each with children, each child a feature with its surfaces. FEATURE_MAP.md is the coverage table derived from it — edit both in one change. Use the underscore form; never create FEATURE-MAP.md.

A feature here is a customer-facing capability, a row in this map, named the way a user would name it. It is not the same thing as a module (modules/<name>, the contract, process, browser and client packages); one feature can be served by several modules, and one module can serve several features.

The entry shape

{
  "id": "observability.tracing",
  "name": "Tracing",
  "description": "Capture LLM calls, spans, inputs/outputs, costs, and latency",
  "surfaces": {
    "code": {
      "sdk": { "python": "…", "typescript": "…", "go": "…" },
      "cli": ["trace search"],
      "hints": {},
      "skill": "tracing",
      "docs": "https://…"
    },
    "platform": { "ui": "/traces", "mcp": ["search_traces"], "skill": null, "docs": null },
    "api": "/api/collector",
    "docs": "https://…"
  },
  "sync": "code-to-platform",
  "produces": ["traces"],
  "consumes": []
}

• code is what a developer writes in their own project; platform is the UI and MCP. api and docs are cross-cutting.
• Values are namespaces, not methods: "langwatch.experiment" means the module.
• sync: null (one mode only), "bidirectional", "code-to-platform", "platform-to-code". Future intent goes in plannedSync, never in sync.
• hints carries a copy-pasteable example per CLI command.
• No aspirational entries. If the code does not serve it, it is not in the map.

Where each surface actually comes from

Updating

1. Read feature-map.json, find the feature by id (dotted: category.feature).
2. Add the value to the right surface array or field. A brand-new feature gets a whole entry under the category whose mental model it belongs to — the hierarchy is the product's, not the code's.
3. Mirror the change in FEATURE_MAP.md.
4. Validate every field you touched against the table above with ls / grep -rn (ripgrep is unreliable in this repo). An entry that names something the code does not serve is worse than a missing one.
5. A route rename must update this file: it is a live surface, not documentation.

Report

The entries added or changed, the code path each was validated against, and anything you found in the map that the code no longer serves.