6. Groups states:

A file MAY contain many tokens and they MAY be nested arbitrarily in groups like so:

{
  "token uno": {
    "$value": "#111111",
    "$type": "color"
  },
  "token group": {
    "token dos": {
      "$value": "2rem",
      "$type": "dimension"
    },
    "nested token group": {
      "token tres": {
        "$value": 33,
        "$type": "number"
      },
      "Token cuatro": {
        "$value": 444,
        "$type": "fontWeight"
      }
    }
  }
}

But 6.2.1 also states:

Groups let token file authors better organize their token files. Related tokens can be nested into groups to align with the team's naming conventions and/or mental model. When manually authoring files, using groups is also less verbose than a flat list of tokens with repeating prefixes.

  "brand": {
    "color": {
      "$type": "color",
      "acid green": {
        "$value": "#00ff66"
      }
    },

...is likely to be more convenient to type and, arguably, easier to read, than:

  "brand-color-acid-green": {
    "$value": "#00ff66",
    "$type": "color"
  },

Does that mean the two are supposed to represent the same thing? Because the first example represents a token "acid green" and the second example represents a different token "brand-color-acid-green".

This seems to suggest there are two different ways to parse a token file: nested or flat. Nested means I should consider the entire token path as part of the token name. Flat means I should assume that the token name is already flat and that any nested paths are just an arbitrary way of grouping items.

It's very confusing to see that:

    "nested token group": {
      "token tres": {
        "$value": 33,
        "$type": "number"
      }

represents a token named token-tres and NOT nested-token-group-token-tres while also seeing that

  "brand": {
    "color": {
      "$type": "color",
      "acid green": {
        "$value": "#00ff66"
      }
    },

represents a token named brand-color-acid-green.

I feel like it should be possible to consume a .token file and be able to output a list of all the available design tokens using only the format. Would it be possible to add more clarification around these concepts?