README.md in ruby-next-0.13.3 vs README.md in ruby-next-0.14.0

@@ -71,10 +71,11 @@
   - [`ruby -ruby-next`](#uby-next)
   - [Logging & Debugging](#logging-and-debugging)
 - [RuboCop](#rubocop)
 - [Using with EOL Rubies](#using-with-eol-rubies)
 - [Proposed & edge features](#proposed-and-edge-features)
+- [Known limitations](#known-limitations)
 
 ## Overview
 
 Ruby Next consists of two parts: **core** and **language**.
 
@@ -198,12 +199,10 @@
 
 - From code by setting `RubyNext::Language.mode = :ast` or `RubyNext::Language.mode = :rewrite`.
 - Via environmental variable `RUBY_NEXT_TRANSPILE_MODE=ast`.
 - Via CLI option ([see below](#cli)).
 
-**NOTE:** For the time being, Unparser doesn't support Ruby 3.0 AST nodes, so we always use rewrite mode in Ruby 3.0+.
-
 ## CLI
 
 Ruby Next ships with the command-line interface (`ruby-next`) which provides the following functionality:
 
 ### `ruby-next nextify`
@@ -229,11 +228,11 @@
         --dry-run                    Print verbose output without generating files
 ```
 
 The behaviour depends on whether you transpile a single file or a directory:
 
-- When transpiling a directory, the `.rbnext` subfolder is created within the target folder with subfolders for each supported Ruby versions (e.g., `.rbnext/2.6`, `.rbnext/2.7`, `.rbnext/3.0`). If you want to create only a single version (the smallest), you can also pass `--single-version` flag. In that case, no version directory is created (i.e., transpiled files go into `.rbnext`).
+- When transpiling a directory, the `.rbnext` subfolder is created within the target folder with subfolders for each supported Ruby versions (e.g., `.rbnext/2.6`, `.rbnext/2.7`, `.rbnext/3.0`, etc.). If you want to create only a single version (the smallest), you can also pass `--single-version` flag. In that case, no version directory is created (i.e., transpiled files go into `.rbnext`).
 
 - When transpiling a file and providing the output path as a _file_ path, only a single version is created. For example:
 
 ```sh
 $ ruby-next nextify my_ruby.rb -o my_ruby_next.rb -V
@@ -281,10 +280,12 @@
   - ArrayDeconstruct
   - EnumerableFilterMap
   - EnumeratorLazyFilterMap
   - HashDeconstructKeys
   - StructDeconstruct
+
+...
 ```
 
 ### CLI configuration file
 
 You can define CLI options in the `.rbnextrc` file located in the root of your project to avoid adding them every time you run `ruby-next`.
@@ -520,16 +521,41 @@
 
 - Set `RUBY_NEXT_EDGE=1` or `RUBY_NEXT_PROPOSED=1` environment variable.
 
 ### Supported edge features
 
-`Array#intersect?` ([#15198](https://bugs.ruby-lang.org/issues/15198))
+It's too early, Ruby 3.1 has just been released. See its features in the [supported features list](./SUPPORTED_FEATURES.md).
 
 ### Supported proposed features
 
 - _Method reference_ operator (`.:`) ([#13581](https://bugs.ruby-lang.org/issues/13581)).
+- Binding non-local variables in pattern matching (`42 => @v`) ([#18408](https://bugs.ruby-lang.org/issues/18408)).
 
-- Shorthand Hash/kwarg notation (`data = {x, y}` or `foo(x:, y:)`) ([#15236](https://bugs.ruby-lang.org/issues/15236)).
+## Known limitations
+
+Ruby Next aims to be _reasonably compatible_ with MRI. That means, some edge cases could be uncovered. Below is the list of known limitations.
+
+For gem authors, we recommend testing against all supported versions on CI to make sure you're not hit by edge cases.
+
+### Enumerable methods
+
+Using refinements (`using RubyNext`) for modules could lead to unexpected behaviour in case there is also a `prepend` for the same module in Ruby <2.7.
+To eliminate this, we also refine Array (when appropriate), but other enumerables could be affected.
+
+See [this issue](https://bugs.ruby-lang.org/issues/13446) for details.
+
+### `Refinement#import_methods`
+
+- Doesn't support importing methods generated with `eval`.
+- Doesn't support aliases (both `alias` and `alias_method`).
+- In JRuby, importing attribute accessors/readers/writers is not supported.
+- When using AST transpiling in runtime, likely fails to import methods from a transpiled files (due to the updated source location).
+
+See the [original PR](https://github.com/ruby-next/ruby-next/pull/85) for more details.
+
+### Other
+
+See [Parser's known issues](https://github.com/whitequark/parser#known-issues).
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at [https://github.com/ruby-next/ruby-next](ttps://github.com/ruby-next/ruby-next).