Document markup and improve choice tags

MARKUP_GUIDELINES.md

@@ -0,0 +1,81 @@
+# Markup Guidelines
+
+This file documents author-facing Ink tag conventions. The active parser normalizes tags into structured `StoryTag` objects before they reach the UI.
+
+## Implemented Tag Forms
+
+Use bracket tags for titles, filenames, and longer text:
+
+```ink
+#chapter[Eibenreith]
+#image[statue.png](square)
+#music[Kaiserpunk Waltz.mp3](crossfade, loop, lead=8)
+#sfx[church-bells.ogg](max=8, fade)
+#score[You reached an ending.]
+#achievement[First Steps]
+#alert[Try examining the room.]
+```
+
+Use colon tags for short identifiers, categories, and choice keys:
+
+```ink
+#action:movement
+#key:l
+#sort:last
+#gated:noble
+```
+
+Bare flags are accepted as tags with no value:
+
+```ink
+#optional
+```
+
+## Choice Metadata
+
+Choice tags are placed on the Ink choice they belong to:
+
+```ink
+* [__Schaue__: Aus dem Fenster.]
+  #action:orientation
+  #key:l
+```
+
+Implemented choice metadata:
+
+- `#key:x`: reserves keyboard key `X` for the choice.
+- `#letter[x]`: older equivalent for reserving keyboard key `X`.
+- `#action:group` or `#action[group]`: stores a category/template hint.
+
+The current UI renders all choices in one list. Explicit keys are assigned first; choices without explicit keys receive `A` through `Z` in visible order. Digits, grouping columns, stable shuffling, `#optional`, `#gated[...]`, and `#sort[...]` are documented authoring conventions or future metadata, not fully implemented UI behavior yet.
+
+## Popup And End-State Tags
+
+These tags may appear as Ink global tags, paragraph tags, or empty tag-only lines. They are dispatched through the same tag channel as media tags.
+
+```ink
+#score[You reached the quiet ending.]
+#error[The story ended unexpectedly.]
+#achievement[First Steps]
+#alert[Try examining objects before using them.]
+```
+
+- `#score[...]`: intended ending. When the turn reaches `inputMode: end`, the UI shows a localized ending popup with the tag value as the optional message.
+- `#error[...]`: unrecoverable ending. The UI shows a localized error popup with the tag value as the optional message. The Ink engine emits this automatically if Ink runs out of content without an explicit `#score[...]` or `#error[...]`.
+- `#achievement[...]`: queued localized achievement popup while the game continues.
+- `#alert[...]`: queued localized player hint/tutorial popup while the game continues.
+
+## Existing Media And Structure Tags
+
+```ink
+#chapter[Title]
+#section
+#textblock
+#image[filename.png](landscape)
+#image[filename.png](portrait pause=2)
+#image[filename.png](square lead=1.5)
+#music[track.mp3](crossfade, loop, lead=4)
+#sfx[file.ogg](max=8 fade fade-duration=2)
+```
+
+Asset filenames resolve relative to the configured image, music, and sound folders.