From c41c266ac1dfdeed56a21b67ad578ae9159dc988 Mon Sep 17 00:00:00 2001
From: hypercross <helios.tnak@gmail.com>
Date: Mon, 10 Aug 2026 16:07:17 +0800
Subject: [PATCH] docs(bgm): document role= on code block info strings

---
 docs/bgm-format.md | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/docs/bgm-format.md b/docs/bgm-format.md
index d0d2519..2b2760d 100644
--- a/docs/bgm-format.md
+++ b/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