A few more nits. Make it much more clear that you really ought to be …

…using the CLI, not the API, unless you're special.

docs/documentation.html

@@ -54,21 +54,36 @@ <h2 id="table-of-contents">Table of Contents</h2>
 
 <h2 id="installation">Installation</h2>
 
-<h3 id="installation-node-js">Node.js</h3>
+<p>Note: When you pre-generate a grammar using the
+  <a href="#generating-a-parser-command-line">Peggy Command Line Interface</a>,
+  no runtime is required, and Peggy can be a development-only dependency.</p>
 
-<p>To use the <code>peggy</code> command, install Peggy globally:</p>
+<h3 id="installation-node-js">Node.js</h3>
 
-<pre><code class="language-console">$ npm install -g peggy</code></pre>
+<p>To use the <code>peggy</code> command:</p>
 
-<p>To use the JavaScript API, install Peggy locally:</p>
+<pre><code class="language-console">$ npm install --save-dev peggy</code></pre>
+<pre><code class="language-console">$ npx peggy --help</code></pre>
 
-<pre><code class="language-console">$ npm install peggy</code></pre>
+In your <code>package.json</code> file, you can do something like:
 
-<p>If you need both the <code>peggy</code> command and the JavaScript API,
-  install Peggy both ways.</p>
+<pre><code class="language-json">
+{
+  "scripts": {
+    "parser": "peggy -o lib/parser.js --format es src/parser.peggy"
+  }
+}
+</code></pre>
 
 <h3 id="installation-browser">Browser</h3>
 
+<p>NOTE: For most uses of Peggy, use the command line version at build time,
+  outputting the generated parser to a static JavaScript file that you can
+  import later as needed.  The API is most useful for tooling that needs to
+  process user-edited grammar source, such as the <a href="online.html">online
+  Peggy editor</a>.  Generating the parser at runtime can be much slower than
+  executing pre-generated code.</p>
+
 <p>The easiest way to use Peggy from the browser is to pull the latest version
   from a CDN. Either of these should work:</p>
 
@@ -90,9 +105,10 @@ <h3 id="installation-browser">Browser</h3>
 
 <h2 id="generating-a-parser">Generating a Parser</h2>
 
-<p>Peggy generates parser from a grammar that describes expected input and can
-  specify what the parser returns (using semantic actions on matched parts of the
-  input). Generated parser itself is a JavaScript object with a simple API.</p>
+<p>Peggy generates a parser from a grammar that describes the expected input
+  and can specify what the parser returns (using semantic actions on matched
+  parts of the input). The generated parser itself is a JavaScript object with a
+  <a href="#using-the-parser">small API</a>.</p>
 
 <h3 id="generating-a-parser-command-line">Command Line</h3>
 
@@ -110,7 +126,7 @@ <h3 id="generating-a-parser-command-line">Command Line</h3>
 <p>If you omit both input and output file, standard input and standard output
   are used.</p>
 
-<p>By default, the generated parser is in the Node.js module format. You can
+<p>By default, the generated parser is in the commonjs module format. You can
   override this using the <code>--format</code> option.</p>
 
 <p>You can tweak the generated parser with several options:</p>
@@ -285,6 +301,9 @@ <h3 id="generating-a-parser-command-line">Command Line</h3>
 
 <h3 id="generating-a-parser-javascript-api">JavaScript API</h3>
 
+<p>Note again: this is an advanced usage of Peggy.  Most of the core use cases
+  of Peggy should prefer to generate a grammar at build time using the CLI.</p>
+
 <p>In Node.js, require the Peggy parser generator module:</p>
 
 <pre><code class="language-javascript">const peggy = require("peggy");</code></pre>
@@ -293,6 +312,10 @@ <h3 id="generating-a-parser-javascript-api">JavaScript API</h3>
 
 <pre><code class="language-javascript">import peggy from "peggy";</code></pre>
 
+<p>With some configurations of Typescript, you might need:</p>
+
+<pre><code class="language-javascript">import * as peggy from "peggy";</code></pre>
+
 <p>For use in browsers, include the Peggy library in your web page or
   application using the <code>&lt;script&gt;</code> tag. If Peggy detects an
   <a href="https://requirejs.org/docs/whyamd.html">AMD</a> loader, it will define
@@ -304,7 +327,7 @@ <h3 id="generating-a-parser-javascript-api">JavaScript API</h3>
 
 <pre><code class="language-javascript">const parser = peggy.generate("start = ('a' / 'b')+");</code></pre>
 
-<p>The method will return generated parser object or its source code as a string
+<p>The method will return a generated parser object or its source code as a string
   (depending on the value of the <code>output</code> option — see below). It will
   throw an exception if the grammar is invalid. The exception will contain a
   <code>message</code> property with more details about the error.</p>
@@ -378,8 +401,10 @@ <h3 id="generating-a-parser-javascript-api">JavaScript API</h3>
   <dd>
     <p>A string, one of:</p>
     <ul>
-      <li><code>"parser"</code> - return generated parser object.</li>
       <li><code>"source"</code> - return parser source code as a string.</li>
+      <li><code>"parser"</code> - return a generated <a href="#using-the-parser">parser object</a>.  This is
+        just the "source" output that has had `eval` run on it.  As such, some
+        formats, such as "es" may not work.</li>
       <li><code>"source-and-map"</code> - return a
         <a href="https://github.com/mozilla/source-map#sourcenode"><code>SourceNode</code></a>
         object; you can get source code by calling <code>toString()</code>
@@ -446,7 +471,8 @@ <h4 id="error-reporting">Error Reporting</h4>
 
 <h2 id="using-the-parser">Using the Parser</h2>
 
-<p>To use the generated parser, call its <code>parse</code>
+<p>To use the generated parser, import it using your selected module approach
+  if needed, then call its <code>parse</code>
   method and pass an input string as a parameter. The method will return a parse
   result (the exact value depends on the grammar used to generate the parser) or
   throw an exception if the input is invalid. The exception will contain