Added a user-facing CLI reference page to the documentation.

.docker/cli.dockerfile

@@ -83,7 +83,7 @@ COPY composer.json composer.* patches.lock.* .env* auth* /app/
 #;< VORTEX_DEV
 # Copy the in-tree drevops/vortex-tooling package so the path repository
 # declared in composer.json can resolve during the build. Consumer sites
-# get the package from packagist; the Vortex CLI strips this block.
+# get the package from packagist; the CLI install command strips this block.
 COPY .vortex/tooling /app/.vortex/tooling
 #;> VORTEX_DEV
 

.vortex/CLAUDE.md

@@ -97,7 +97,7 @@ subscripts remain Bash.
 template's root `composer.json` requires
 `"drevops/vortex-tooling": "^2.0@alpha"` and the path repository pins
 `"versions": {"drevops/vortex-tooling": "2.0.0-alpha1"}` so the in-repo copy
-resolves during development. The CLI strips that path repository from
+resolves during development. The CLI install command strips that path repository from
 consumer sites; until a `2.0` pre-release is published to Packagist, scaffolded
 sites cannot resolve the tooling - acceptable during 2.x pre-release
 development. Once a `2.0` release is published, switch the constraint to a plain

.vortex/cli/CLAUDE.md

@@ -80,7 +80,7 @@ within a file that survives the install regardless of the choice. Use them
   conditionally while the rest of the file stays.
 - The choice can flip independently of any other selection.
 
-**Do not** wrap an entire file in fences if the CLI removes the whole
+**Do not** wrap an entire file in fences if the install command removes the whole
 file via `File::remove($t . '/path/to/file')` based on the same selection.
 The file removal is the conditional behaviour - the fences are dead noise and
 add visual clutter to the shipped file. Examples:

.vortex/cli/README.md

@@ -1,4 +1,4 @@
-# Vortex installer
+# Vortex CLI
 
 ## Maintenance
 
@@ -8,6 +8,6 @@
 
 ### Releasing
 
-The installer is packaged as a PHAR and deployed to https://www.vortextemplate.com/install
+The CLI is packaged as a PHAR and deployed to https://www.vortextemplate.com/install
 upon each GitHub release or for every branch to a branch containing the
-`release-docs` or `release-installer` in the name.
+`release-docs` or `release-cli` in the name.

.vortex/cli/src/Utils/Normalizer.php

@@ -5,7 +5,7 @@
 namespace DrevOps\VortexCli\Utils;
 
 /**
- * Installer configuration.
+ * Install configuration.
  *
  * Install config is a config of the install command.
  *

.vortex/cli/tests/Functional/Command/InstallCommandTest.php

@@ -601,7 +601,7 @@ public static function dataProviderInstallCommandMajorGate(): \Iterator {
       TRUE,
       'Failed to download Vortex.',
     ];
-    yield 'unstamped installer skips gate' => [
+    yield 'unstamped CLI skips gate' => [
       NULL,
       '{"require": {"drevops/vortex-tooling": "^2.0.0"}}',
       TRUE,

.vortex/cli/tests/Functional/FunctionalTestCase.php

@@ -71,7 +71,7 @@ protected function runNonInteractiveInstall(?string $dst = NULL, array $options
     }
 
     // Skip the database fetch in demo mode as it is not needed for the
-    // installer's tests.
+    // CLI's tests.
     Env::put(Config::IS_DEMO_DB_FETCH_SKIP, '1');
 
     $this->applicationRun($args, [], $expect_fail);

.vortex/cli/tests/Functional/Handlers/AbstractHandlerProcessTestCase.php

@@ -12,9 +12,9 @@
 use PHPUnit\Framework\Attributes\RunInSeparateProcess;
 
 /**
- * Abstract base class for installer tests.
+ * Abstract base class for install tests.
  *
- * Provides common test logic for all installer test scenarios.
+ * Provides common test logic for all install test scenarios.
  * Run `ahoy update-snapshots` from `.vortex/` to update test snapshots.
  */
 abstract class AbstractHandlerProcessTestCase extends FunctionalTestCase {

.vortex/cli/tests/Functional/PharTest.php

@@ -37,7 +37,8 @@ protected function setUp(): void {
     parent::setUp();
 
     // We use 'Star Wars' theme for the tests, so setting up SUT directory
-    // so that the installer can gather the answers from the directory name.
+    // so that the install command can gather the answers from the directory
+    // name.
     static::$sut = static::locationsMkdir(static::$workspace . DIRECTORY_SEPARATOR . 'star_wars');
 
     // Copy the PHAR file to the SUT directory.
@@ -111,7 +112,7 @@ protected function runInstallationWithPhar(string $phar_path, array $options = [
     ];
     $options += $defaults;
 
-    // The interactive mode is not supported in the tests as installer
+    // The interactive mode is not supported in the tests as the CLI
     // uses Laravel\Prompts which require a real TTY or a series of fallback
     // callbacks to be defined. These callbacks are not implemented yet, so
     // we enforce the non-interactive mode for the tests.

.vortex/cli/tests/Unit/EnvTest.php

@@ -11,9 +11,7 @@
 use DrevOps\VortexCli\Utils\File;
 
 /**
- * Class InstallerDotEnvTest.
- *
- * InstallerDotEnvTest fixture class.
+ * Tests for the Env class.
  */
 #[CoversClass(Env::class)]
 #[RunTestsInSeparateProcesses]

.vortex/cli/tests/Unit/ValidatorTest.php

@@ -9,7 +9,7 @@
 use DrevOps\VortexCli\Utils\Validator;
 
 /**
- * Class InstallerHelpersTest.
+ * Tests for the Validator class.
  */
 #[CoversClass(Validator::class)]
 class ValidatorTest extends UnitTestCase {

.vortex/docs/content/cli.mdx

@@ -0,0 +1,142 @@
+---
+sidebar_position: 4
+---
+
+# CLI
+
+The **Vortex** CLI is a single self-contained binary that scaffolds a new project from the template and updates an existing one. It ships as a PHAR, so it needs nothing installed beyond PHP.
+
+```shell title="Download and run"
+curl -SsL https://www.vortextemplate.com/install > vortex.phar && php vortex.phar
+```
+
+For the step-by-step walkthrough of setting up a new project, see [Installation](./installation).
+
+## Commands
+
+| Command              | Purpose                                              |
+|----------------------|------------------------------------------------------|
+| `install`            | Install **Vortex** from a remote or local repository |
+| `check-requirements` | Check that the required tools are installed          |
+| `build`              | Build the site using `ahoy build`                    |
+
+`install` is the default command, so `php vortex.phar` and `php vortex.phar install` do the same thing.
+
+```shell title="List every command and option"
+php vortex.phar list
+php vortex.phar install --help
+```
+
+### install
+
+Downloads the template, asks the configuration questions, and writes the result into the destination directory. Run it in an existing **Vortex** project to update that project instead.
+
+| Option                | Short | Description                                                                     |
+|-----------------------|-------|---------------------------------------------------------------------------------|
+| `--destination`       |       | Destination directory. Defaults to the current directory                        |
+| `--root`              |       | Path used to resolve relative paths. Defaults to the current directory          |
+| `--uri`               | `-l`  | Remote or local repository URI, with an optional git ref after `#`              |
+| `--no-interaction`    | `-n`  | Do not ask any interactive question                                             |
+| `--config`            | `-c`  | JSON string, or path to a JSON file, of CLI configuration                       |
+| `--prompts`           | `-p`  | JSON string, or path to a JSON file, of prompt answers keyed by prompt ID       |
+| `--schema`            |       | Output the prompt schema as JSON and exit                                       |
+| `--validate`          |       | Validate the supplied answers without installing                                |
+| `--build`             | `-b`  | Run the build after installing, without prompting                               |
+| `--no-cleanup`        |       | Do not remove the CLI after a successful installation                           |
+| `--agent-help`        |       | Output instructions for AI agents and exit                                      |
+
+The `--uri` option accepts a git ref after `#`, which selects what to install:
+
+```shell title="Choosing what to install"
+php vortex.phar install --uri=https://github.com/drevops/vortex.git
+php vortex.phar install --uri=https://github.com/drevops/vortex.git#stable
+php vortex.phar install --uri=https://github.com/drevops/vortex.git#1.2.3
+```
+
+### check-requirements
+
+Checks for the tools a **Vortex** project needs: Docker, Docker Compose, Ahoy and Pygmy.
+
+| Option         | Short | Description                                            |
+|----------------|-------|--------------------------------------------------------|
+| `--only`       | `-o`  | Comma-separated subset of requirements to check         |
+| `--no-summary` |       | Hide the summary listing tool versions                  |
+
+### build
+
+Builds the site by running `ahoy build` in the project directory.
+
+| Option                     | Short | Description                                          |
+|----------------------------|-------|------------------------------------------------------|
+| `--profile`                | `-p`  | Build from the install profile instead of a database |
+| `--skip-requirements-check`|       | Skip checking for the required tools                  |
+
+## Non-interactive use
+
+Every question can be answered up front, which is what makes the CLI usable from a script or a pipeline. Ask for the schema, build an answers object from it, optionally validate, then install:
+
+```shell title="Discover the available prompts"
+php vortex.phar install --schema
+```
+
+```shell title="Validate answers without installing"
+php vortex.phar install --validate --prompts='{"name":"My Project","hosting_provider":"lagoon"}'
+```
+
+```shell title="Install non-interactively"
+php vortex.phar install --no-interaction --prompts=prompts.json --destination=./my-project
+```
+
+`--prompts` keys are the prompt IDs from `--schema`. `--config` is separate: it carries CLI configuration such as the repository and ref, not prompt answers.
+
+:::tip Using an AI agent
+
+`--agent-help` prints the whole workflow above as instructions written for an AI coding agent:
+
+```shell
+php vortex.phar install --agent-help
+```
+
+:::
+
+## Environment variables
+
+Variables are scoped by what they configure. Settings that belong to the CLI itself use the `VORTEX_CLI_` prefix; settings that belong to the `install` command use `VORTEX_CLI_INSTALL_`.
+
+| Variable                           | Purpose                                       |
+|------------------------------------|-----------------------------------------------|
+| `VORTEX_CLI_VERSION`               | Override the version stamped into the binary  |
+| `VORTEX_CLI_URL`                   | Where `ahoy update-vortex` downloads the PHAR |
+| `VORTEX_CLI_PATH`                  | Local PHAR path; overrides the URL            |
+| `VORTEX_CLI_URL_CACHE_BUST`        | Cache-busting parameter for the URL           |
+| `VORTEX_CLI_INSTALL_TMP_DIR`       | Working directory for the downloaded source   |
+| `VORTEX_CLI_INSTALL_TEMPLATE_REPO` | Template repository to install from           |
+| `VORTEX_CLI_INSTALL_PROMPT_<ID>`   | Answer for a single prompt, by prompt ID       |
+
+:::note Superseded variable names
+
+These variables were previously prefixed with `VORTEX_INSTALLER_`. The old names still work: when the current name is unset, the matching legacy name supplies the value and the run prints a notice naming its replacement. The fallback exists to ease migration and will be removed in a future major version.
+
+:::
+
+## Distribution
+
+The CLI is published to three stable paths, each served with no file extension:
+
+| Path                                        | Contents                |
+|---------------------------------------------|-------------------------|
+| `https://www.vortextemplate.com/install`    | The current major       |
+| `https://www.vortextemplate.com/v1/install` | The `1.x` line          |
+| `https://www.vortextemplate.com/v2/install` | The `2.x` line          |
+
+The bare `/install` path always serves the current major. Each per-major path is built from that major's own branch, so pinning to `/v1/install` or `/v2/install` keeps you on that line.
+
+A build refuses to run against a project from a different major version and points you at the matching path instead, so an accidental cross-major update cannot happen silently.
+
+## Updating an existing project
+
+Inside a **Vortex** project, `ahoy update-vortex` downloads the CLI and runs it for you - you do not need to fetch the binary yourself. See [Updating Vortex](./updating-vortex).
+
+## Maintaining the CLI
+
+For how the CLI is developed, tested and released, see [Maintenance / CLI](./contributing/maintenance/cli).

.vortex/docs/content/contributing/maintenance/cli.mdx

@@ -68,12 +68,12 @@ The core flow is:
 ### Conditional token system
 
 In addition to string substitution for handling simple replacements and
-additions, the CLI uses a token system to conditionally exclude entire
+additions, the install command uses a token system to conditionally exclude entire
 blocks of content from template files. This simplifies the management of
 optional features — rather than requiring complex logic to surgically remove
 lines from configuration files, scripts, or documentation, maintainers simply
 wrap the relevant content in token markers. When a feature is not selected
-during installation, the CLI removes everything between the markers.
+during installation, the install command removes everything between the markers.
 
 **Markdown**:
 
@@ -93,7 +93,7 @@ Content removed if feature not selected
 
 ## Distribution
 
-The PHAR is published to three stable, extensionless paths:
+The PHAR is published to three stable paths, each served with no file extension:
 
 | Path                                        | Contents                |
 |---------------------------------------------|-------------------------|
@@ -147,7 +147,7 @@ is tested in isolation with mocks provided by
 
 ### Functional testing with snapshots
 
-For every test permutation, the CLI *initiates a fresh project* from the
+For every test permutation, the install command *initiates a fresh project* from the
 Vortex template with a specific combination of user selections and runs
 assertions against the resulting files. Because a single template change can
 affect a hundred plus installation permutations, snapshot testing makes it easy to
@@ -216,7 +216,7 @@ cd .vortex/cli
 UPDATE_SNAPSHOTS=1 ./vendor/bin/phpunit --filter "testHandlerProcess.*baseline"
 ```
 
-When `UPDATE_SNAPSHOTS` is set, the CLI *runs for every permutation*,
+When `UPDATE_SNAPSHOTS` is set, the install command *runs for every permutation*,
 initiates a fresh project for each scenario, and automatically updates the
 fixture files to match the current output. The resulting changes appear as
 diffs in version control, making it straightforward to review exactly how a

.vortex/docs/content/development/visual-regression.mdx

@@ -326,5 +326,5 @@ Adjust `VR_DIFFY_PR_LABEL`, `VR_DIFFY_AUTO_BRANCHES`, and
 Remove `diffy` from `VORTEX_NOTIFY_CHANNELS` and delete the
 `.github/workflows/test-vr.yml` workflow file.
 
-To remove the integration entirely, re-run the CLI and answer
+To remove the integration entirely, re-run the install command and answer
 "no" to the visual regression prompt.

.vortex/docs/content/drupal/composer-json.mdx

@@ -74,7 +74,7 @@ outside the default Packagist repository.
 - `drevops/vortex-tooling` (path): A local
   [path repository](https://getcomposer.org/doc/05-repositories.md#path)
   pointing at `.vortex/tooling`, used only inside the **Vortex** repository so
-  the in-tree tooling package resolves during development. The CLI strips
+  the in-tree tooling package resolves during development. The CLI install command strips
   this entry during site creation, so your project installs
   [`drevops/vortex-tooling`](https://github.com/drevops/vortex-tooling) from
   Packagist instead.

.vortex/docs/content/faqs.mdx

@@ -43,8 +43,8 @@ discuss any of the decisions made in **Vortex**.
 ## Isn't this overkill for my project?
 
 **Vortex** provides a full feature set to all projects, regardless of size. You
-can simply opt-out of features you don't need when installing: the CLI
-provides an interactive prompt to select only the features you want.
+can simply opt-out of features you don't need when installing: the CLI install
+command provides an interactive prompt to select only the features you want.
 
 If you're sure you don't need certain features, **Vortex** may not be the
 right fit. That said, many developers have discovered useful tools and

.vortex/docs/content/installation.mdx

@@ -9,8 +9,10 @@ import TabItem from '@theme/TabItem';
 # Installation
 
 These steps take you from an empty directory to a deployed site. The **Vortex**
-CLI scaffolds your codebase; the remaining steps connect it to your hosting
-platform and continuous integration provider. Follow them in order.
+CLI install command scaffolds your codebase; the remaining steps connect it to
+your hosting platform and continuous integration provider. Follow them in order.
+
+For the full command, option and environment-variable reference, see [CLI](./cli).
 
 ## Installing Vortex into a new project
 
@@ -42,6 +44,8 @@ get instructions for a non-interactive, programmatic installation:
 curl -SsL https://www.vortextemplate.com/install > vortex.phar && php vortex.phar --agent-help
 ```
 
+See [CLI](./cli#non-interactive-use) for the schema, validation and answer-file workflow.
+
 :::
 
 :::tip Choosing a Vortex version
@@ -209,7 +213,7 @@ runs the tests, and deploys according to your configuration.
 
 ## Installing Vortex into an existing project
 
-The CLI cannot predict the state of your project, so initialize **Vortex**
+The CLI install command cannot predict the state of your project, so initialize **Vortex**
 into a new directory and merge your existing project into it.
 
 :::warning
@@ -222,7 +226,7 @@ Back up your project before proceeding.
 
 2. In your existing project, create a new branch and remove all files except the `.git` directory.
 
-3. Run the CLI ([step 1](#1-install-vortex)) to produce a clean **Vortex** installation, then commit it.
+3. Run the install command ([step 1](#1-install-vortex)) to produce a clean **Vortex** installation, then commit it.
 
 4. Copy your files back from the temporary directory, overriding the installed ones. Review the diff and selectively keep changes - merge `composer.json` by hand (preserving **all** of **Vortex's** entries) and regenerate `composer.lock` with `composer install`.
 

.vortex/docs/content/updating-vortex.mdx

@@ -27,7 +27,7 @@ secure and up-to-date.
 `1.x` project receives the latest `1.x` release and is never moved to `2.x`
 automatically. Moving to a new major is a deliberate step: run that major's
 CLI (for example `https://www.vortextemplate.com/v2/install`) against your
-project.
+project. See [CLI](./cli#distribution) for the per-major paths.
 
 :::