JoshuaKGoldberg · JoshuaKGoldberg · Mar 17, 2025 · Mar 16, 2025 · Mar 17, 2025 · Mar 17, 2025
diff --git a/README.md b/README.md
@@ -48,8 +48,8 @@ You can read more about the supported runtime modes in their docs pages:
 You can read more about `create-typescript-app` and the tooling it supports:
 
 1. [**Blocks**](./docs/Blocks.md): a breakdown of all the pieces this template can set up.
-2. [**Options**](./docs/Options.md): granular options to customize how the template is run.
-3. [**FAQs**](./docs/FAQs.md): frequently asked questions
+2. [**CLI**](./docs/CLI.md): providing granular options to customize how the template is run.
+3. [**FAQs**](./docs/FAQs.md): frequently asked questions and troubleshooting
 
 > [!NOTE]  
 > This template is early stage, opinionated, and not endorsed by the TypeScript team.

diff --git a/cspell.json b/cspell.json
@@ -12,6 +12,7 @@
 	"words": [
 		"Anson",
 		"apexskier",
+		"attw",
 		"automerge",
 		"dbaeumer",
 		"infile",

diff --git a/docs/Blocks.md b/docs/Blocks.md
@@ -51,7 +51,7 @@ This table summarizes each block and which base levels they're included in:
 | Vitest                       | `--exclude-vitest`                       |         | ✅     | 💯         |
 | VS Code                      | `--exclude-vs-code`                      |         |        | 💯         |
 
-See also [Options](./Options.md) for how to customize the way template is run.
+See also [CLI](./CLI.md) for customizing templated repositories when running `npx create-typescript-app`.
 
 ## "Minimal" Base Level
 

diff --git a/docs/CLI.md b/docs/CLI.md
@@ -0,0 +1,85 @@
+# CLI
+
+`create-typescript-app` supports all the flags supported by [Bingo CLI](https://www.create.bingo/cli)s.
+It also provides a collection of custom flags per [Bingo CLI > Template Flags](https://www.create.bingo/cli#template-flags).
+
+```shell
+npx create-typescript-app
+```
+
+## Required Flags
+
+These options can only be inferred when running on an existing repository.
+Each will be prompted for when creating a new repository if not explicitly provided:
+
+| Flag            | Description                                    |
+| --------------- | ---------------------------------------------- |
+| `--description` | 'Sentence case.' description of the repository |
+| `--directory`   | which directory and repository name to use     |
+| `--preset`      | starting set of tooling to use                 |
+
+`npx create-typescript-app` provides three `--preset` options:
+
+1. **Minimal**: Just bare starter tooling: building, formatting, linting, and type checking.
+2. **Common**: Bare starters plus testing and automation for all-contributors and releases.
+3. **Everything**: The most comprehensive tooling imaginable: sorting, spellchecking, and more!
+
+For example, to create a new repository with the _Everything_ preset and prompt for `description` and `directory`:
+
+```shell
+npx create-typescript-app --preset everything
+```
+
+Pre-populating all required base options:
+
+```shell
+npx create-typescript-app --directory my-app --description "My app! 💖" --preset everything
+```
+
+See [Bingo > Stratum > Concepts > Templates > `--preset`](https://www.create.bingo/engines/stratum/concepts/templates#--preset) for more details on presets.
+
+## Optional Flags
+
+The following flags may be provided on the CLI to customize their values.
+Each defaults to a value based on the running system, including an repository if transitioning one.
+
+| Flag           | Type       | Description                                                                                                         | Default                                                                               |
+| -------------- | ---------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `--access`     | `string`   | Which [`npm publish --access`](https://docs.npmjs.com/cli/commands/npm-publish#access) to release npm packages with | `"public"` (TODO: file issue for `readAccess`)                                        |
+| `--author`     | `string`   | Username on npm to publish packages under                                                                           | An existing npm author, or the currently logged in npm user, or `owner.toLowerCase()` |
+| `--bin`        | `string`   | Value to set in `package.json`'s `"bin"` property, per [FAQs > How can I use `bin`?](./FAQs.md#how-can-i-use-bin)   | _(none)_                                                                              |
+| `--email`      | `string`   | Email address to be listed as the point of contact in docs and packages (e.g. `[email protected]`)        | Yours from `gh`, `git config`, or `npm whoami`                                        |
+| `--emoji`      | `string`   | decorative emoji to use in descriptions and docs                                                                    | The last emoji from `description`, or `"💖"`                                          |
+| `--funding`    | `string`   | GitHub organization or username to mention in `funding.yml`                                                         | The same as `owner`                                                                   |
+| `--keywords`   | `string[]` | Any number of keywords to include in `package.json`                                                                 | _(none)_                                                                              |
+| `--owner`      | `string`   | Organization or user owning the repository                                                                          | Yours from `gh` or `git config`                                                       |
+| `--pnpm`       | `string`   | pnpm version for `package.json`'s `packageManager` field                                                            | Existing value in `package.json` if it exists                                         |
+| `--repository` | `string`   | Name for the new repository                                                                                         | The same as `--directory`                                                             |
+| `--title`      | `string`   | 'Title Case' title for the repository                                                                               | Title-cased `repository`                                                              |
+| `--version`    | `string`   | package version to publish as and store in `package.json`                                                           | Existing value in `package.json` if it exists, or `"0.0.0"`                           |
+
+For example, customizing the npm author and funding source to different values than what would be inferred:
+
+```shell
+npx create-typescript-app --author my-npm-username --funding MyGitHubOrganization
+```
+
+Array flags can be specified as space-delineated strings and/or multiple times.
+For example, customizing keywords to three:
+
+```shell
+npx create-typescript-app --keywords eslint --keywords "javascript typescript"
+```
+
+## Block Exclusion Flags
+
+Per [Bingo > Stratum > Concepts > Templates > Exclusion Options](https://www.create.bingo/engines/stratum/concepts/templates#exclusion-options), individual "Blocks" of tooling may be excluded from running.
+Each Block may be excluded with a CLI flag whose name matches `--exclude-*`.
+
+For example, initializing with all tooling except for Renovate:
+
+```shell
+npx create-typescript-app --exclude-renovate
+```
+
+See [Blocks.md](./Blocks.md) for the list of blocks, which presets contain them, and their corresponding `--exclude-*` flags.
diff --git a/docs/Configuration Files.md b/docs/Configuration Files.md
@@ -0,0 +1,177 @@
+# Configuration Files
+
+`create-typescript-app` supports a `create-typescript-app.config.js` configuration file per [Bingo > Configuration](https://www.create.bingo/configuration).
+Bingo configuration files are generally used for describing complex options that can't be inferred from existing repositories.
+`create-typescript-app` is built on the [Stratum engine](https:://create.bingo/engines/stratum/about), so its configuration files adhere to [Bingo > Stratum > Details > Configurations](https://www.create.bingo/engines/stratum/details/configurations):
+
+- [`options`](#options): any type-safe options the template has declared
+- [`refinements`](#refinements): any customizations specified by the template
+
+> [!TIP]  
+> `create-typescript-app` defaults `options` to their values in an existing repository.
+> You most likely only need to use `refinements` to specify changes that can't be inferred.
+
+## `options`
+
+Any type-safe options the template has declared.
+This includes the options described in [CLI](./CLI.md).
+
+Some of create-typescript-app's options are rich objects, typically very long strings, or otherwise not reasonable on the CLI.
+These options are generally only programmatically used internally, but can still be specified in a configuration file:
+
+| Option           | Description                                                              | Default (If Available)                                    |
+| ---------------- | ------------------------------------------------------------------------ | --------------------------------------------------------- |
+| `contributors`   | AllContributors contributors to store in `.all-contributorsrc`           | Existing contributors in the file, or just your username  |
+| `documentation`  | any additional docs to add to `.github/DEVELOPMENT.md`                   | Extra content in `.github/DEVELOPMENT.md`                 |
+| `existingLabels` | existing labels to switch to the standard template labels                | Existing labels on the repository from the GitHub API     |
+| `explainer`      | additional `README.md` sentence(s) describing the package                | Extra content in `README.md` after badges and description |
+| `guide`          | link to a contribution guide to place at the top of development docs     | Block quote on top of `.github/DEVELOPMENT.md`            |
+| `logo`           | local image file and alt text to display near the top of the `README.md` | First non-badge image's `alt` and `src` in `README.md`    |
+| `node`           | Node.js engine version(s) to pin and require a minimum of                | Values from `.nvmrc` and `package.json`'s `"engines"`     |
+| `packageData`    | additional properties to include in `package.json`                       | Existing values in `package.json`                         |
+| `rulesetId`      | GitHub branch ruleset ID for main branch protections                     | Existing ruleset on the `main` branch from the GitHub API |
+| `usage`          | Markdown docs to put in `README.md` under the `## Usage` heading         | Existing usage lines in `README.md`                       |
+
+For example, changing `node` versions to values different from what would be inferred:
+
+```ts
+// create-typescript-app.config.js
+import { createConfig } from "create-typescript-app";
+
+export default createConfig({
+	options: {
+		node: {
+			minimum: ">=20.19.0",
+			pinned: "22.14.0",
+		},
+	},
+});
+```
+
+> [!TIP]  
+> Running `npx create-typescript-app` will apply any new `options` values to the repository.
+> You can generally remove `options` from your configuration file after running `npx create-typescript-app`.
+
+## `refinements`
+
+[Refinements](https://www.create.bingo/engines/stratum/details/configurations#refinements) can be used to modify the "Blocks" of tooling provided by create-typescript-app.
+
+See [Blocks.md](./Blocks.md) for the list of blocks, which presets contain them, and their corresponding `--exclude-*` flags.
+
+### `addons`
+
+Any additional [Addons](https://www.create.bingo/engines/stratum/concepts/blocks#addons) provided to Blocks provided by the selected Preset.
+
+For example, this configuration file adds the word `"joshuakgoldberg"` to the CSpell Block's Addons:
+
+```ts
+// create-typescript-app.config.js
+import { blockCSpell, createConfig } from "create-typescript-app";
+
+export default createConfig({
+	refinements: {
+		addons: [
+			blockCSpell({
+				words: ["joshuakgoldberg"],
+			}),
+		],
+	},
+});
+```
+
+Running `npx create-typescript-app` in a repository with that configuration file would add `"joshuakgoldberg"` to the `words` in `cspell.json`.
+
+### `blocks`
+
+Any customizations to the Blocks provided by the selected Preset.
+
+#### `add`
+
+Any Blocks to add to what the Preset provides.
+
+For example, this configuration file adds in `create-typescript-app`'s provided "arethetypeswrong" Block:
+
+```ts
+// create-typescript-app.config.js
+import { blockAreTheTypesWrong, createConfig } from "create-typescript-app";
+
+export default createConfig({
+	refinements: {
+		blocks: {
+			add: [blockAreTheTypesWrong],
+		},
+	},
+});
+```
+
+Running `npx create-typescript-app` in a repository with that configuration file would add in the created outputs from `blockAreTheTypesWrong`.
+
+#### `exclude`
+
+Any Blocks to exclude from what the Preset provides.
+
+For example, this configuration file omits the default _"This package was templated with..."_ notice that comes with `create-typescript-app`:
+
+```ts
+// create-typescript-app.config.js
+import { blockTemplatedBy, createConfig } from "create-typescript-app";
+
+export default createConfig({
+	refinements: {
+		blocks: {
+			exclude: [blockTemplatedBy],
+		},
+	},
+});
+```
+
+Running `npx create-typescript-app` in a repository with that configuration file would not include that Block, and so its generated README.md would not include the notice.
+
+#### Custom Blocks and Addons
+
+Custom Blocks can provide Addons to any other Blocks, including those provided by the package.
+This allows your repositories to blend in seamlessly with the features provided by your Template.
+
+For example, to add an [`@arethetypeswrong/cli`](https://www.npmjs.com/package/@arethetypeswrong/cli) lint task to the `package.json` file, a repository using the `create-typescript-app` Template could create and use a custom Block:
+
+```ts
+// blockLintAreTheTypesWrong.js
+import { base, blockPackageJson } from "create-typescript-app";
+
+export const blockLintAreTheTypesWrong = base.createBlock({
+	about: {
+		name: "Lint Are The Types Wrong",
+	},
+	produce() {
+		return {
+			addons: [
+				blockPackageJson({
+					properties: {
+						devDependencies: {
+							"@arethetypeswrong/cli": "0.17.3",
+						},
+						scripts: {
+							"lint:arethetypeswrong": "attw --pack .",
+						},
+					},
+				}),
+			],
+		};
+	},
+});
+```
+
+```ts
+// create-typescript-app.config.js
+import { createConfig } from "create-typescript-app";
+
+import { blockLintAreTheTypesWrong } from "./blockLintAreTheTypesWrong.js";
+
+export default createConfig({
+	refinements: {
+		blocks: {
+			add: [blockLintAreTheTypesWrong],
+		},
+	},
+});
+```
diff --git a/docs/FAQs.md b/docs/FAQs.md
@@ -164,7 +164,7 @@ The four presets correspond to what have seemed to be the most common user needs
    - Tooling added in this preset should be essential for a TypeScript repository that additionally automates useful GitHub tasks: contributor recognition, release management, and testing.
 3. **Everything**: Power users (including this repository) who want as much of the latest and greatest safety checks and standardization as possible.
 
-Note that you can always customize exactly which preset you use per [Options](./Options.md).
+Note that you can always customize exactly which preset you use per [CLI](./CLI.md).
 
 ## Why does this package include so many tools?
 

diff --git a/docs/Options.md b/docs/Options.md
diff --git a/docs/Setup.md b/docs/Setup.md
@@ -29,7 +29,7 @@ Hooray! 🥳
 ## Options
 
 You can customize which pieces of tooling are provided and the options they're created with.
-See [Options.md](./Options.md).
+See [CLI.md](./CLI.md).
 
 For example, skipping the _"This package was templated with..."_ block:
 

diff --git a/docs/Transition.md b/docs/Transition.md
@@ -38,10 +38,10 @@ Hooray! 🥳
 > You'll want to review each of the changes.
 > There will almost certainly be some incorrect changes you'll need to fix.
 
-## Options
+## CLI Options
 
 You can customize which pieces of tooling are provided and the options they're created with.
-See [Options.md](./Options.md).
+See [CLI.md](./CLI.md).
 
 For example, skipping the _"This package was templated with..."_ block: