docs: refactor project documentation into inidividual files with more…

docs/README.md

@@ -0,0 +1,17 @@
+# Emulsify CLI Documentation
+
+These docs expand on the short project README and are organized by the task a project user or maintainer is usually trying to complete.
+
+| Topic                                                             | Use This When                                                                                                          |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| [CLI Reference](./cli-reference.md)                               | Looking up commands, aliases, options, and examples.                                                                   |
+| [Project Initialization](./project-initialization.md)             | Creating a new Emulsify project from a starter, including Drupal and non-interactive examples.                         |
+| [Systems](./systems.md)                                           | Listing built-in systems, installing systems, using custom system repositories, or understanding system configuration. |
+| [Components](./components.md)                                     | Listing installable components, installing components and dependencies, using dry runs, and creating local components. |
+| [Project Configuration](./configuration.md)                       | Understanding `project.emulsify.json`, system and variant references, structure mappings, and validation.              |
+| [Component Template Overrides](./component-template-overrides.md) | Replacing the built-in `component create` templates with project-level templates.                                      |
+| [Hooks And Cache](./hooks-and-cache.md)                           | Understanding starter hooks, system install hooks, script execution, and the `~/.emulsify/cache` repository cache.     |
+| [Development](./development.md)                                   | Setting up this repository, understanding source layout, and running checks.                                           |
+| [Release](./release.md)                                           | Understanding CI, develop version bumps, semantic-release, and npm publishing.                                         |
+| [Contributors](./contributors.md)                                 | Viewing project contributors moved out of the root README.                                                             |
+| [Website Usage Copy](./emulsify-info-cli-updates.md)              | Copy-ready usage content for the `emulsify.info` CLI page.                                                             |

docs/cli-reference.md

@@ -0,0 +1,136 @@
+# CLI Reference
+
+Emulsify CLI installs as the `emulsify` binary.
+
+```bash
+emulsify --help
+emulsify <command> --help
+```
+
+The examples below reflect the command definitions in `src/index.ts` and the generated help from the built `dist/index.js` entry point.
+
+## Commands
+
+| Command                             | Alias                         | Description                                                      |
+| ----------------------------------- | ----------------------------- | ---------------------------------------------------------------- |
+| `emulsify init [name] [path]`       |                               | Initialize an Emulsify project from a starter.                   |
+| `emulsify system list`              | `emulsify system ls`          | List built-in systems available for installation.                |
+| `emulsify system install [name]`    |                               | Install a system in the current Emulsify project.                |
+| `emulsify component list`           | `emulsify component ls`       | List components available from the installed system and variant. |
+| `emulsify component install [name]` | `emulsify component i [name]` | Install a component from the installed system and variant.       |
+| `emulsify component create [name]`  | `emulsify component c [name]` | Generate a new local component in the current project.           |
+
+## `init`
+
+```bash
+emulsify init [name] [path]
+```
+
+Options:
+
+| Option                               | Description                                                                                                                                    |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `-m, --machineName <machineName>`    | Machine-friendly project folder and config name. If omitted, the CLI derives it from the project name. Drupal machine names use underscores.   |
+| `-s, --starter <repository>`         | Starter Git repository to clone.                                                                                                               |
+| `-c, --checkout <commit/branch/tag>` | Starter commit, branch, or tag to check out after clone.                                                                                       |
+| `-p, --platform <platform>`          | Platform to use when auto-detection is unavailable or should be overridden. Built-in starters are currently available for `none` and `drupal`. |
+| `-y, --yes`                          | Accept default values for missing init options without prompting.                                                                              |
+
+Examples:
+
+```bash
+emulsify init "My Project" ./projects --platform none
+emulsify init "My Theme" ./web/themes/custom --platform drupal
+emulsify init "My Theme" ./web/themes/custom --platform drupal --machineName my_custom_theme
+emulsify init "My Project" ./projects --starter https://github.com/emulsify-ds/emulsify-starter --checkout main --platform none
+```
+
+## `system list`
+
+```bash
+emulsify system list
+emulsify system ls
+```
+
+Lists the built-in system names and repositories known to this CLI version.
+
+## `system install`
+
+```bash
+emulsify system install [name]
+```
+
+Options:
+
+| Option                               | Description                                                                                                                                      |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `-r, --repository <repository>`      | Install a system from a specific Git repository. Custom repository URLs must end in `.git`.                                                      |
+| `-c, --checkout <commit/branch/tag>` | Checkout to use. This is required when `--repository` is used.                                                                                   |
+| `-a, --all`                          | Install every component in the selected variant. Without this flag, only components marked `required: true` are installed during system install. |
+
+Examples:
+
+```bash
+emulsify system install compound
+emulsify system install compound --all
+emulsify system install --repository https://github.com/example/example-system.git --checkout v1.0.0
+```
+
+## `component list`
+
+```bash
+emulsify component list
+emulsify component ls
+```
+
+Lists components available from the installed system and selected variant. Output uses the component structure followed by the component name, for example `atoms -> buttons`.
+
+## `component install`
+
+```bash
+emulsify component install [name]
+emulsify component i [name]
+```
+
+Options:
+
+| Option        | Description                                                                                         |
+| ------------- | --------------------------------------------------------------------------------------------------- |
+| `-f, --force` | Replace an existing component destination without prompting.                                        |
+| `-a, --all`   | Install all available components instead of one named component.                                    |
+| `--dry-run`   | Preview dependencies, destinations, overwrite behavior, and copy operations without changing files. |
+
+Examples:
+
+```bash
+emulsify component install card
+emulsify component install card --dry-run
+emulsify component i accordion --force
+emulsify component install --all
+```
+
+## `component create`
+
+```bash
+emulsify component create [name]
+emulsify component c [name]
+```
+
+Options:
+
+| Option                        | Description                                                                           |
+| ----------------------------- | ------------------------------------------------------------------------------------- |
+| `-d, --directory <directory>` | Variant structure name where the component should be created.                         |
+| `-f, --format <format>`       | Component format to generate. Supported values are `default` and `sdc`.               |
+| `-y, --yes`                   | Replace an existing generated component without prompting.                            |
+| `--dry-run`                   | Preview destination and generated files without writing, removing, or creating files. |
+
+Examples:
+
+```bash
+emulsify component create promo-card --directory molecules --format default
+emulsify component create promo-card --directory molecules --format default --dry-run
+emulsify component c teaser --directory molecules --format sdc --yes
+```
+
+In a non-interactive environment, pass both `--directory` and `--format`; otherwise the command errors instead of waiting for prompts that cannot be answered.

docs/component-template-overrides.md

@@ -0,0 +1,128 @@
+# Component Template Overrides
+
+`emulsify component create` uses built-in templates by default. A project can replace any generated artifact with a matching override file under `.cli/templates/`.
+
+Overrides replace known generated files one-for-one. They do not add arbitrary extra files and they do not change which artifacts are generated.
+
+## Directory Layout
+
+Default component overrides:
+
+```text
+.cli/templates/default/component.twig
+.cli/templates/default/component.scss
+.cli/templates/default/component.yml
+.cli/templates/default/component.stories.js
+```
+
+SDC component overrides:
+
+```text
+.cli/templates/sdc/component.twig
+.cli/templates/sdc/component.scss
+.cli/templates/sdc/component.component.yml
+.cli/templates/sdc/component.js
+.cli/templates/sdc/component.stories.js
+```
+
+For each generated artifact, the CLI looks for the matching override first. If the file is missing, the built-in template is used.
+
+## Supported Tokens
+
+Override files can use double-brace tokens.
+
+| Token             | Example Value For `featured-item` |
+| ----------------- | --------------------------------- |
+| `{{ filename }}`  | `featured-item`                   |
+| `{{ className }}` | `featured-item`                   |
+| `{{ camelName }}` | `featuredItem`                    |
+| `{{ snakeName }}` | `featured_item`                   |
+| `{{ humanName }}` | `Featured Item`                   |
+| `{{ directory }}` | `base`                            |
+| `{{ format }}`    | `default` or `sdc`                |
+
+Whitespace inside the braces is optional:
+
+```twig
+{{humanName}}
+{{ humanName }}
+```
+
+Unknown tokens are left unchanged and logged as warnings. Empty override files are ignored and the built-in template is used.
+
+## Example Default Twig Override
+
+Create `.cli/templates/default/component.twig`:
+
+```twig
+{% set classes = [
+  '{{ className }}',
+] %}
+
+<section class="{{ className }}" data-component="{{ filename }}">
+  {% block content %}
+  {% endblock %}
+</section>
+```
+
+Then generate a component:
+
+```bash
+emulsify component create featured-item --directory base --format default
+```
+
+The generated file is:
+
+```text
+components/00-base/featured-item/featured-item.twig
+```
+
+## Example SDC Metadata Override
+
+Create `.cli/templates/sdc/component.component.yml`:
+
+```yaml
+name: {{ humanName }}
+status: stable
+props:
+  type: object
+  properties:
+    {{ snakeName }}_title:
+      type: string
+      title: Title
+slots:
+  content:
+    title: Content
+```
+
+Generate the SDC component:
+
+```bash
+emulsify component create featured-item --directory base --format sdc
+```
+
+The generated file is:
+
+```text
+components/00-base/featured-item/featured-item.component.yml
+```
+
+## Partial Overrides
+
+Override only the artifacts you need. For example, a project can override Twig and keep the built-in SCSS, data, and story templates:
+
+```text
+.cli/templates/default/component.twig
+```
+
+All missing override files fall back to the built-in builders.
+
+## Dry-Run With Overrides
+
+Dry runs do not write files, but they still resolve the selected format, structure, and output paths:
+
+```bash
+emulsify component create featured-item --directory base --format default --dry-run
+```
+
+Use dry runs to confirm the component destination before replacing or adding override files.