fix: separate RDoc and YARD references (#2232)

## Summary

- keep the RDoc cheatsheet focused on RDoc markup and directives
- move YARD-specific tags into a dedicated YARD cheatsheet
- update both references against current official documentation

## Why

The existing RDoc sheet mixes RDoc directives with YARD tags such as
`@param`, `@return`, `@raise`, and `@option`. This makes the examples
look like native RDoc syntax.

The new split keeps each reference accurate and easier to scan.

Closes #2176.
Closes #2172.

## Checks

- Prettier passes for both Markdown files
- frontmatter and fenced code blocks verified
- no promotional links or unrelated changes

yard.md

@@ -0,0 +1,141 @@
+---
+title: YARD
+category: Markup
+intro: |
+  Quick reference for YARD tags in Ruby documentation.
+---
+
+### Method documentation
+{: .-prime}
+
+```ruby
+# Downloads a page.
+#
+# @param url [String] the page URL
+# @param directory [String] the output directory
+# @return [String] the saved file path
+# @raise [DownloadError] if the request fails
+# @example Download into the default directory
+#   download("https://example.com/")
+def download(url, directory: "pages")
+end
+```
+
+YARD tags begin with `@` at the start of a comment line.
+
+## Parameters and return values
+
+### Parameters
+
+```ruby
+# @param name [String] the user name
+# @param count [Integer] the number of retries
+# @param enabled [Boolean] whether retries are enabled
+```
+
+For keyword parameters, use `@param`.
+
+### Return values
+
+```ruby
+# @return [String] the matching name
+# @return [nil] if no match exists
+```
+
+Use multiple `@return` tags for distinct return cases.
+
+### Exceptions
+
+```ruby
+# @raise [AccountBalanceError] if funds are insufficient
+```
+
+### Options hash
+
+```ruby
+# @param opts [Hash] message options
+# @option opts [String] :subject the subject
+# @option opts [String] :from ("nobody") the sender
+# @option opts [String] :to the recipient
+# @option opts [String] :body ("") the message body
+```
+
+Use `@option` for keys inside an options hash, not for keyword parameters.
+
+## Types
+
+### Common forms
+
+| Form | Meaning |
+| --- | --- |
+| `[String]` | One type |
+| `[String, nil]` | Alternative types |
+| `[Array<String>]` | Collection members |
+| `[Hash{Symbol => String}]` | Key and value types |
+| `[#read]` | Duck type |
+| `[Boolean]` | `true` or `false` |
+| `[void]` | Return value unused |
+
+YARD type declarations are conventions rather than Ruby runtime checks.
+
+### Reference tags
+
+```ruby
+# @param user [String] the user name
+# @param host [String] the host name
+def clean(user, host)
+end
+
+# @param (see #clean)
+def activate(user, host)
+end
+```
+
+`(see OBJECT)` copies matching tag data from another documented object.
+
+## Examples and links
+
+### Example
+
+```ruby
+# @example Reverse a string
+#   "hello".reverse #=> "olleh"
+```
+
+The optional text after `@example` becomes the example title.
+
+### Object references
+
+```text
+{User}
+{User#name}
+{User#name Display name}
+```
+
+### Common tags
+
+| Tag | Use |
+| --- | --- |
+| `@api` | API audience |
+| `@author` | Author name |
+| `@deprecated` | Replacement guidance |
+| `@example` | Usage example |
+| `@note` | Important note |
+| `@option` | Options hash key |
+| `@param` | Method parameter |
+| `@private` | Private API |
+| `@raise` | Raised exception |
+| `@return` | Return value |
+| `@see` | Related object or URL |
+| `@since` | First release |
+| `@todo` | Pending work |
+| `@yieldparam` | Block parameter |
+| `@yieldreturn` | Block return value |
+
+## Also see
+{: .-one-column}
+
+- <https://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md>
+- <https://www.rubydoc.info/gems/yard/file/docs/Tags.md>
+- <https://yardoc.org/types.html>
+{: .-also-see}