📝 document style tag registry methods

docs/api/index.md

@@ -71,6 +71,10 @@ BitLogger API navigation.
 - [text-style.md](./text-style.md)
 - [style-tag-registry-type.md](./style-tag-registry-type.md)
 - [style-tag-registry.md](./style-tag-registry.md)
+- [style-tag-registry-set-tag.md](./style-tag-registry-set-tag.md)
+- [style-tag-registry-get.md](./style-tag-registry-get.md)
+- [style-tag-registry-contains.md](./style-tag-registry-contains.md)
+- [style-tag-registry-define-alias.md](./style-tag-registry-define-alias.md)
 - [default-style-tag-registry.md](./default-style-tag-registry.md)
 - [text-formatter-type.md](./text-formatter-type.md)
 - [text-formatter.md](./text-formatter.md)

docs/api/style-tag-registry-contains.md

@@ -0,0 +1,78 @@
+---
+name: style-tag-registry-contains
+group: api
+category: formatter
+update-time: 20260613
+description: Check whether a StyleTagRegistry contains a named style tag.
+key-word:
+    - style
+    - registry
+    - contains
+    - public
+---
+
+## Style-tag-registry-contains
+
+Check whether a `StyleTagRegistry` contains one named tag. This is the boolean inspection companion to `get(...)` when code only needs existence rather than the stored style value.
+
+### Interface
+
+```moonbit
+pub fn StyleTagRegistry::contains(self : StyleTagRegistry, name : String) -> Bool {
+```
+
+#### input
+
+- `self : StyleTagRegistry` - Registry to inspect.
+- `name : String` - Tag name to check.
+
+#### output
+
+- `Bool` - `true` when the registry contains the tag, otherwise `false`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The tag name is normalized before the presence check.
+- This method only checks the current registry value, not the global registry or builtin tag set.
+- It is useful when code should branch on tag availability without unpacking `TextStyle?`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Simple Presence Check
+
+When setup code should verify that a registry carries one custom tag:
+```moonbit
+let tags = style_tag_registry().set_tag("accent", fg=Some("#4cc9f0"))
+println(tags.contains("accent"))
+```
+
+In this example, the result is `true`.
+
+#### When Need To Guard Optional Registry Behavior
+
+When later logic should only run for existing tags:
+```moonbit
+let tags = style_tag_registry()
+if tags.contains("danger") {
+  println("defined")
+}
+```
+
+In this example, the guarded block runs only when the local registry already defines the tag.
+
+### Error Case
+
+e.g.:
+- Missing tags simply produce `false`.
+
+- If code needs the actual stored style value, `get(...)` is the better API.
+
+### Notes
+
+1. This is the lightest-weight way to probe one registry entry.
+
+2. The method is useful in tests that only care about tag presence.

docs/api/style-tag-registry-define-alias.md

@@ -0,0 +1,83 @@
+---
+name: style-tag-registry-define-alias
+group: api
+category: formatter
+update-time: 20260613
+description: Define one style-tag name as an alias of another style entry.
+key-word:
+    - style
+    - registry
+    - alias
+    - public
+---
+
+## Style-tag-registry-define-alias
+
+Define one tag name as an alias of another style entry. This helper copies an existing style into the current registry so alternate names can reuse the same visual meaning.
+
+### Interface
+
+```moonbit
+pub fn StyleTagRegistry::define_alias(
+  self : StyleTagRegistry,
+  name : String,
+  target : String,
+) -> StyleTagRegistry {
+```
+
+#### input
+
+- `self : StyleTagRegistry` - Registry to update.
+- `name : String` - Alias name to create.
+- `target : String` - Existing tag name whose style should be copied.
+
+#### output
+
+- `StyleTagRegistry` - The same registry value after alias resolution is attempted.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The method first checks the current registry for `target`.
+- If the local registry does not have the target, it falls back to the global style tag registry.
+- If the global registry also lacks the target, it falls back to the built-in tag set.
+- When no matching target exists in any of those sources, the registry is returned unchanged.
+- The resolved style is copied into `name`; this is not a live reference that tracks future target changes.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Friendlier Local Alias
+
+When one project wants a local tag name that mirrors an existing style:
+```moonbit
+let tags = default_style_tag_registry().define_alias("danger", "error")
+```
+
+In this example, `danger` is stored using the same style as the resolved `error` tag.
+
+#### When Need To Alias A Custom Local Tag
+
+When several names should share one custom style definition:
+```moonbit
+let tags = style_tag_registry()
+  .set_tag("accent", fg=Some("#4cc9f0"), bold=true)
+  .define_alias("brand", "accent")
+```
+
+In this example, `brand` copies the current local `accent` style into the registry.
+
+### Error Case
+
+e.g.:
+- If the target tag cannot be resolved locally, globally, or from builtins, no new alias entry is added.
+
+- If callers need a tag with modified style fields rather than an exact copy, use `set_tag(...)` instead.
+
+### Notes
+
+1. This helper is useful for keeping multiple semantic names visually aligned.
+
+2. Alias resolution prefers the current registry before consulting global or built-in tags.

docs/api/style-tag-registry-get.md

@@ -0,0 +1,80 @@
+---
+name: style-tag-registry-get
+group: api
+category: formatter
+update-time: 20260613
+description: Look up one style tag from a StyleTagRegistry.
+key-word:
+    - style
+    - registry
+    - lookup
+    - public
+---
+
+## Style-tag-registry-get
+
+Look up one named style tag from a `StyleTagRegistry`. This is the direct inspection helper for tests, setup validation, or custom formatter logic that needs the stored `TextStyle` value.
+
+### Interface
+
+```moonbit
+pub fn StyleTagRegistry::get(self : StyleTagRegistry, name : String) -> TextStyle? {
+```
+
+#### input
+
+- `self : StyleTagRegistry` - Registry to inspect.
+- `name : String` - Tag name to look up.
+
+#### output
+
+- `TextStyle?` - `Some(style)` when the tag exists, otherwise `None`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The tag name is normalized before lookup.
+- This method only checks the current registry value passed as `self`.
+- Missing names return `None` instead of raising an error.
+- This is useful when code needs the style value itself rather than only presence or absence.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need To Inspect A Custom Tag
+
+When setup code or tests should verify that a tag was stored:
+```moonbit
+let tags = style_tag_registry().set_tag("accent", fg=Some("#4cc9f0"))
+match tags.get("accent") {
+  Some(style) => ignore(style)
+  None => panic()
+}
+```
+
+In this example, the registry returns the stored `TextStyle` for the tag.
+
+#### When Need Graceful Missing-tag Handling
+
+When code should tolerate an absent entry:
+```moonbit
+let tags = style_tag_registry()
+let maybe_style = tags.get("missing")
+```
+
+In this example, `maybe_style` becomes `None` instead of failing.
+
+### Error Case
+
+e.g.:
+- There is no separate failure path for a missing tag; the method returns `None`.
+
+- If code only needs a yes-or-no existence check, `contains(...)` is simpler than reading the optional style value.
+
+### Notes
+
+1. Use this method when callers need the stored `TextStyle` itself.
+
+2. This lookup does not automatically fall back to the global registry or builtin tags.

docs/api/style-tag-registry-set-tag.md

@@ -0,0 +1,94 @@
+---
+name: style-tag-registry-set-tag
+group: api
+category: formatter
+update-time: 20260613
+description: Add or override a named style tag in a StyleTagRegistry.
+key-word:
+    - style
+    - registry
+    - tag
+    - public
+---
+
+## Style-tag-registry-set-tag
+
+Add or override one named style tag inside a `StyleTagRegistry`. This is the main mutation helper for building custom formatter tag vocabularies in code.
+
+### Interface
+
+```moonbit
+pub fn StyleTagRegistry::set_tag(
+  self : StyleTagRegistry,
+  name : String,
+  style~ : TextStyle = text_style(),
+  fg~ : String? = None,
+  bg~ : String? = None,
+  bold~ : Bool = false,
+  dim~ : Bool = false,
+  italic~ : Bool = false,
+  underline~ : Bool = false,
+) -> StyleTagRegistry {
+```
+
+#### input
+
+- `self : StyleTagRegistry` - Registry to update.
+- `name : String` - Tag name to define or replace.
+- `style : TextStyle` - Base style value to store before overlay options are applied.
+- `fg : String?` - Optional foreground color override.
+- `bg : String?` - Optional background color override.
+- `bold : Bool` - Whether to enable bold in the stored style.
+- `dim : Bool` - Whether to enable dim in the stored style.
+- `italic : Bool` - Whether to enable italic in the stored style.
+- `underline : Bool` - Whether to enable underline in the stored style.
+
+#### output
+
+- `StyleTagRegistry` - The same registry value after the named entry is updated.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The tag name is normalized before storage, so lookup is case-insensitive in practice.
+- The explicit `fg`, `bg`, and boolean flags are merged on top of the supplied `style` value.
+- Calling `set_tag(...)` for an existing name replaces that entry with the merged result.
+- The method returns the registry itself so calls can be chained while building formatter configuration.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Custom Semantic Tag
+
+When text output should recognize a project-specific tag name:
+```moonbit
+let tags = style_tag_registry()
+  .set_tag("accent", fg=Some("#4cc9f0"), bold=true)
+```
+
+In this example, `<accent>...</>` becomes available to formatters that use the registry.
+
+#### When Need To Start From An Existing Style
+
+When a tag should reuse a prepared `TextStyle` and then tweak one field:
+```moonbit
+let base = text_style(fg=Some("#22cc88"))
+let tags = style_tag_registry().set_tag("success", style=base, underline=true)
+```
+
+In this example, underline is layered on top of the base style value.
+
+### Error Case
+
+e.g.:
+- If style markup is disabled in the formatter, defining tags here has no visible effect on rendered output.
+
+- If the same tag name is set multiple times, the latest stored value wins.
+
+### Notes
+
+1. Use this method when custom tag definitions should live in a local registry instead of the global one.
+
+2. `define_alias(...)` is the better fit when one tag name should mirror an existing tag exactly.