From 438a3bdffced823be20f5df8994217b307ec2d5e Mon Sep 17 00:00:00 2001
From: "Yukihiro \"Matz\" Matsumoto" <matz@ruby.or.jp>
Date: Fri, 27 Feb 2026 22:03:39 +0900
Subject: [PATCH] docs: fix version labels, add navigation aids

limitations.md: use consistent CRuby/mruby labels for remaining
entries that still had specific version strings.

language.md: add upfront summary of major CRuby differences so
porting developers see the key gotchas before reading the full doc.

capi.md: add table of contents for navigating the 800+ line
reference.

Co-authored-by: Claude <noreply@anthropic.com>
---
 doc/guides/capi.md     | 21 +++++++++++++++++++++
 doc/guides/language.md | 13 +++++++++++++
 doc/limitations.md     |  8 ++++----
 3 files changed, 38 insertions(+), 4 deletions(-)

diff --git a/doc/guides/capi.md b/doc/guides/capi.md
index 7faabc802..d6a94c3d4 100644
--- a/doc/guides/capi.md
+++ b/doc/guides/capi.md
@@ -4,6 +4,27 @@
 
 This document covers the mruby C API for embedding and extending mruby.
 
+**Contents:**
+[Headers](#headers) |
+[State Management](#state-management) |
+[Values](#values) |
+[Defining Classes and Modules](#defining-classes-and-modules) |
+[Defining Methods](#defining-methods) |
+[Parsing Arguments](#parsing-arguments) |
+[Calling Ruby Methods from C](#calling-ruby-methods-from-c) |
+[String Operations](#string-operations) |
+[Array Operations](#array-operations) |
+[Hash Operations](#hash-operations) |
+[Wrapping C Structures](#wrapping-c-structures) |
+[Exception Handling](#exception-handling) |
+[Method Visibility](#method-visibility) |
+[Proc and Block Handling](#proc-and-block-handling) |
+[Fiber API](#fiber-api) |
+[Compilation Contexts](#compilation-contexts) |
+[Precompiled Bytecode](#precompiled-bytecode) |
+[GC Arena](#gc-arena) |
+[Memory Allocation](#memory-allocation)
+
 ## Headers
 
 ```c
diff --git a/doc/guides/language.md b/doc/guides/language.md
index 134e4fa0e..93bb1de6d 100644
--- a/doc/guides/language.md
+++ b/doc/guides/language.md
@@ -7,6 +7,19 @@ mruby implements a subset of the Ruby language, optimized for embedded use.
 For a list of specific behavioral differences, see
 [limitations.md](../limitations.md).
 
+**If you are coming from CRuby**, note these major differences upfront:
+
+- No `require` or `load` — all code is linked at build time
+- No `defined?` keyword — use `respond_to?`, `const_defined?`, etc.
+- No refinements (`refine`, `using`)
+- No `Encoding` class — UTF-8 opt-in via `MRB_UTF8_STRING`
+- Fibers cannot yield across C function boundaries
+- Integer size varies by platform and boxing mode
+- Operators cannot be overridden by user code
+
+See [Key Differences from CRuby](#key-differences-from-cruby) for
+the full list.
+
 ## Syntax
 
 ### Keywords
diff --git a/doc/limitations.md b/doc/limitations.md
index e2e6e178a..953591b08 100644
--- a/doc/limitations.md
+++ b/doc/limitations.md
@@ -201,11 +201,11 @@ class C
 end
 ```
 
-#### Ruby [ruby 3.5.0dev (2025-04-21 85bab61565))]
+#### CRuby
 
 Prints `:append`.
 
-#### mruby [3.5.0 (2025-04-28)]
+#### mruby
 
 Nothing printed (since `include` does not call `append_features` internally).
 
@@ -221,7 +221,7 @@ Pattern matching is only partially supported in mruby. Currently, only the right
 expr => var  # Supported: assigns expr to var
 ```
 
-#### Ruby [ruby 3.0.0+]
+#### CRuby
 
 Full pattern matching with `case/in` syntax and various pattern types:
 
@@ -237,7 +237,7 @@ in {name:, age:}
 end
 ```
 
-#### mruby [current]
+#### mruby
 
 Only rightward assignment with simple variable binding: