docs: update with latest changes

🤦‍♂️ it seems I forgot to document a lot of changes.

README.md

@@ -9,7 +9,7 @@
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![Documentation Status](https://readthedocs.org/projects/copier/badge/?version=latest)](https://copier.readthedocs.io/en/latest/?badge=latest)
 
-A library for rendering project templates.
+A library and CLI app for rendering project templates.
 
 -   Works with **local** paths and **git URLs**.
 -   Your project can include any file and `Copier` can dynamically replace values in any
@@ -31,19 +31,19 @@ A library for rendering project templates.
 -   Use it in your Python code:
 
     ```python
-    from copier import copy
+    from copier import run_auto
 
     # Create a project from a local path
-    copy("path/to/project/template", "path/to/destination")
+    run_auto("path/to/project/template", "path/to/destination")
 
     # Or from a git URL.
-    copy("https://github.com/copier-org/copier.git", "path/to/destination")
+    run_auto("https://github.com/copier-org/copier.git", "path/to/destination")
 
     # You can also use "gh:" as a shortcut of "https://github.com/"
-    copy("gh:copier-org/copier.git", "path/to/destination")
+    run_auto("gh:copier-org/copier.git", "path/to/destination")
 
     # Or "gl:" as a shortcut of "https://gitlab.com/"
-    copy("gl:copier-org/copier.git", "path/to/destination")
+    run_auto("gl:copier-org/copier.git", "path/to/destination")
     ```
 
 -   Or as a command-line tool:
@@ -52,6 +52,43 @@ A library for rendering project templates.
     copier path/to/project/template path/to/destination
     ```
 
+## Basic concepts
+
+Copier is composed of these main concepts:
+
+1. **Templates**. They lay out how to generate the subproject.
+1. **Questionaries**. They are configured in the template. Answers are used to generate
+   projects.
+1. **Projects**. This is where your real program lives. But it is usually generated
+   and/or updated from a template.
+
+Copier targets these main human audiences:
+
+1.  **Template creators**. Programmers that repeat code too much and prefer a tool to do
+    it for them.
+
+    !!! tip
+
+         Copier doesn't replace the DRY principle... but sometimes you simply can't be
+         DRY and you need a DRYing machine...
+
+1.  **Template consumers**. Programmers that want to start a new project quickly, or
+    that want to evolve it comfortably.
+
+Non-humans should be happy also by using copier's CLI or API, as long as their
+expectations are the same as for those humans... and as long as they have feelings.
+
+Templates have these goals:
+
+1. **[Code scaffolding](<https://en.wikipedia.org/wiki/Scaffold_(programming)>)**. Help
+   consumers have a working source code tree as quick as possible. All templates allow
+   scaffolding.
+1. **Code lifecycle management**. When the template evolves, let consumers update their
+   projects. Not all templates allow updating.
+
+Copier tries to have a smooth learning curve that lets you create simple templates that
+can evolve into complex ones as needed.
+
 ## Browse or tag public templates
 
 You can browse public copier templates in GitHub using

docs/comparisons.md

@@ -1,16 +1,24 @@
 # Comparing Copier to other project generators
 
-The subject of project scaffolding has been around for some time, and Copier is just a
-new one in a list of long established good projects. Here's a simple comparison. If you
-find something wrong, please open a PR and fix it! We don't want to be biased, but it's
-easy that we tend to be:
+The subject of
+[code scaffolding](<https://en.wikipedia.org/wiki/Scaffold_(programming)>) has been
+around for some time, and there are long established good projects.
+
+Here's a simple comparison. If you find something wrong, please open a PR and fix these
+docs! We don't want to be biased, but it's easy that we tend to be:
+
+!!! important
+
+    Although Copier was born as a code scaffolding tool, it is today a code lifecycle
+    management tool. This makes it somehow unique. Most tools below are only scaffolders
+    and the comparison is not complete due to that.
 
 <!-- Use https://www.tablesgenerator.com/markdown_tables to maintain this table -->
 
 | Feature                                  | Copier                                   | Cookiecutter                    | Yeoman        |
 | ---------------------------------------- | ---------------------------------------- | ------------------------------- | ------------- |
 | Can template file names                  | Yes                                      | Yes                             | Yes           |
-| Configuration                            | Single or multiple YAML files            | Single JSON file                | JS module     |
+| Configuration                            | Single YAML file<sup>1</sup>             | Single JSON file                | JS module     |
 | Migrations                               | Yes                                      | No                              | No            |
 | Programmed in                            | Python                                   | Python                          | NodeJS        |
 | Requires handwriting JSON                | No                                       | Yes                             | Yes           |
@@ -20,16 +28,16 @@ easy that we tend to be:
 | Task hooks                               | Yes                                      | Yes                             | Yes           |
 | Template in a subfolder                  | Not required, but you choose             | Yes, required                   | Yes, required |
 | Template package format                  | Git repo<sup>2</sup>, Git bundle, folder | Git or Mercurial repo, Zip file | NPM package   |
-| Template updates                         | Yes<sup>4</sup>                          | No                              | No            |
-| Templating engine                        | [Jinja][]<sup>1</sup>                    | [Jinja][]                       | [EJS][]       |
+| Template updates                         | **Yes**<sup>4</sup>                      | No                              | No            |
+| Templating engine                        | [Jinja][]                                | [Jinja][]                       | [EJS][]       |
 
 [jinja]: https://jinja.palletsprojects.com/
 [ejs]: https://ejs.co/
 
 ---
 
-<sup>1</sup> Copier configures Jinja to use `[[ brackets ]]` instead of
-`{{ curly braces }}` by default, but that can be changed per template if needed.
+<sup>1</sup> The file itself can
+[include other YAML files](configuring.md#include-other-yaml-files).
 
 <sup>2</sup> Git repo is recommended to be able to use advanced features such as
 template tagging and smart updates.