docs(bgm): document role= on code block info strings

docs/bgm-format.md

@@ -111,6 +111,37 @@ code block's info string. The name is relative to the current markdown file:
   referencing. To point at a specific yaml block by name, give it an explicit
   `file=`; otherwise its name is content-derived and unstable.
 
+### role= on the info string
+
+A block's `role` can be declared on the info string instead of in the content,
+using the same `role.type#id` shape as the block's identity. `type` and `id`
+are optional — anything not given comes from the content (or from `$variants`
+rows):
+
+````md
+```yaml file=parts/cargo.yaml role=part.cargo
+...
+```
+
+```yaml file=board.yaml role=surface.game#main
+...
+```
+
+```yaml file=game.yaml role=package
+...
+```
+````
+
+- `role=part.cargo` declares a part of type `cargo`; its `id` comes from the
+  content or from `$variants`.
+- `role=surface.game#main` declares a surface of type `game` with id `main`.
+- `role=package` declares a package; it has no type.
+- A `role`/`type`/`id` given on the info string **conflicts** with the same
+  key in the content and errors. `id` on the info string cannot combine with
+  `$variants`, since every row supplies its own `id`.
+- Without `role=`, discovery works exactly as before: the role comes from the
+  content's `role:` field.
+
 ### include
 
 `include` is a list of git-style path patterns — the defs that make up the
@@ -140,6 +171,10 @@ a valid object can either be the root or in the list of the yaml block.
 for all roles except package, `type` and `id` are needed.
 `type#id` is used for identification so that combo must be unique in the package.
 
+A block may declare its role on the info string instead — `role=part.cargo` is
+equivalent to `role: part` + `type: cargo` in the content (see §2). The info
+string and content must not both set the same key.
+
 ### package
 
 The package is the container for a game's definitions. It is declared with a