[doc/ref] Document __builtins__, Str/List method design

I went for the non-polymorphic design, i.e. Str and List are different.

    Str.find(s) -> int       # like Python
    Str.findLast(s) -> int
    Str.includes(s) -> bool

    List.indexOf(item) -> int       # like JS
    List.lastIndexOf(item) -> int   # like JS
    List.contains(item) -> bool

This isn't set in stone.  But here's some justification:

- Avoid "accidentally quadratic" of the 'in' operator - it is defined to
  be O(1), not O(n)
  - the O(n) boolean test operations are includes() and contains()
- Avoid "false polymorphism"
  - Str is NOT a container of substrings.  There are arbitrarily many
    substrings!
  - It's also not a parameterized type

Note that most languages are more polymorphic than this;

- JavaScript uses indexOf/lastIndexOf/includes for both String and Array
- Python is less consistent, but it has index() on both str and list
- Ruby is pretty polymorphic

However, they do NOT use the UTF-8 string model that we use.  JavaScript
strings are treated as an array of 16 bit code units, and Python strings
are an array of 32 bit code units.

So I think these things justify a different API.  We have NEITHER the
Python nor JavaScript string model.

doc/ref/chap-special-var.md

@@ -81,6 +81,12 @@ consults `__defaults__` after consulting `ENV`.  For example:
 
 <!-- TODO: consider renaming to DEF.PS1 ? -->
 
+### `__builtins__`
+
+An object that contains names visible in every module.
+
+If a name is not visible in the local scope, or module global scope, then it's
+looked up in `__builtins__`.
 
 ### `_this_dir`
 
@@ -144,10 +150,13 @@ The exit status of all the process subs in the last command.
 
 ### _reply
 
-YSH `read` sets this variable:
+Builtins that `read` set this variable:
+
+    read --all < foo.txt
+    = _reply  # => 'contents of file'
 
-    read --all < myfile
-    echo $_reply
+    json read < foo.json
+    = _reply  # => (Dict)  {}
 
 ## Oils VM
 

doc/ref/feature-index.md

@@ -97,6 +97,7 @@ OSH:
 - [`use`](chap-builtin-cmd.html#use)
 - [`is-main`](chap-builtin-cmd.html#is-main)
 - provide (TODO)
+- [`_this_dir`](chap-special-var.html#_this_dir)
 - [`__provide__`](chap-special-var.html#__provide__)
 - An imported module is an [`Obj`][Obj] with an [`__invoke__`][__invoke__]
   method
@@ -168,3 +169,19 @@ Also see [the Unicode doc](../unicode.html).
 
 [io]: chap-type-method.html#io
 [vm]: chap-type-method.html#vm
+
+### Namespaces
+
+- [`ENV`](chap-special-var.html#ENV)
+- [`__builtins__`](chap-special-var.html#__builtins__)
+
+<!--
+
+TODO:
+
+- __modules__
+- does vm.getFrame() belong?
+
+-->
+
+

doc/ref/toc-ysh.md

@@ -44,7 +44,8 @@ error handling, and more.
   [Numbers]        Int
                    Float
                    Range
-  [String]         Str       X find()           replace()
+  [String]         Str       X find()         X findLast()
+                             X contains()       replace()
                                trim()           trimStart()      trimEnd()
                                startsWith()     endsWith()
                                upper()          lower()
@@ -54,9 +55,11 @@ error handling, and more.
                    Match       group()          start()          end()
                              X groups()       X groupDict()
   [Containers]     List        List/append()    pop()            extend()
-                               indexOf()      X insert()       X remove()
+                               indexOf()      X lastIndexOf()  X includes()
+                             X insert()       X remove()
                                reverse()      X List/clear()
                    Dict        erase()        X Dict/clear()   X accum()
+                             X update()
                    Place       setValue()
   [Code Types]     Func        BuiltinFunc      BoundFunc
                    Proc        BuiltinProc
@@ -345,7 +348,8 @@ X [External Lang] BEGIN   END   when (awk)
 </h2>
 
 ```chapter-links-special-var
-  [YSH Vars]      ARGV                ENV                   __defaults__
+  [YSH Vars]      ARGV                ENV
+                  __defaults__        __builtins__
                   _this_dir
   [YSH Status]    _error
                   _pipeline_status    _process_sub_status