JoshuaKGoldberg · JoshuaKGoldberg · Aug 25, 2023 · Aug 23, 2023 · Aug 23, 2023 · Aug 23, 2023
diff --git a/.github/DEVELOPMENT.md b/.github/DEVELOPMENT.md
@@ -44,7 +44,7 @@ Each should be shown in VS Code, and can be run manually on the command-line:
 - `pnpm lint` ([ESLint](https://eslint.org) with [typescript-eslint](https://typescript-eslint.io)): Lints JavaScript and TypeScript source files
 - `pnpm lint:knip` ([knip](https://github.com/webpro/knip)): Detects unused files, dependencies, and code exports
 - `pnpm lint:md` ([Markdownlint](https://github.com/DavidAnson/markdownlint)): Checks Markdown source files
-- `pnpm lint:package` ([npm-package-json-lint](https://npmpackagejsonlint.org/)): Lints the `package.json` file
+- `pnpm lint:package-json` ([npm-package-json-lint](https://npmpackagejsonlint.org/)): Lints the `package.json` file
 - `pnpm lint:packages` ([pnpm dedupe --check](https://pnpm.io/cli/dedupe)): Checks for unnecessarily duplicated packages in the `pnpm-lock.yml` file
 - `pnpm lint:spelling` ([cspell](https://cspell.org)): Spell checks across all source files
 
@@ -91,6 +91,15 @@ pnpm tsc --watch
 
 As described in the `README.md` file and `docs/`, this template repository comes with three scripts that can set up an existing or new repository.
 
+Each follows roughly the same general flow:
+
+1. `bin/index.ts` uses `bin/mode.ts` determines which of the three setup scripts to run
+2. `readOptions` parses in options from local files, Git commands, npm APIs, and/or files on disk
+3. `runOrRestore` wraps the setup script's main logic in a friendly prompt wrapper
+4. The setup script wraps each portion of its main logic with `withSpinner`
+   - Each step of setup logic is generally imported from within `src/steps`
+5. A call to `outro` summarizes the results for the user
+
 > **Warning**
 > Each setup script overrides many files in the directory they're run in.
 > Make sure to save any changes you want to preserve before running them.

diff --git a/.github/workflows/lint-package.yml → .github/workflows/lint-package-json.yml b/.github/workflows/lint-package.yml → .github/workflows/lint-package-json.yml
@@ -4,9 +4,9 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - uses: ./.github/actions/prepare
-      - run: pnpm lint:package
+      - run: pnpm lint:package-json
 
-name: Lint Package
+name: Lint Package JSON
 
 on:
   pull_request: ~

diff --git a/README.md b/README.md
@@ -40,12 +40,12 @@ First make sure you have the following installed:
 - [Node.js](https://nodejs.org)
 - [pnpm](https://pnpm.io)
 
-This repository comes with two scripts to set up an existing or new repository with tooling.
+This repository comes with three script forms to set up an existing or new repository with tooling.
 Use the corresponding docs page to get started:
 
-- [Initializing from the template](./docs/InitializationFromTemplate.md): creating a new repository with the [_Use this template_](https://github.com/JoshuaKGoldberg/template-typescript-node-package/generate) button on GitHub _(recommended)_
-- [Initializing from the terminal](./docs/InitializationFromTerminal.md): creating a new repository locally on the command-line
-- [Migrating an existing repository](./docs/Migration.md): adding this template's tooling on top of an existing repository
+- [Creating from the terminal](./docs/Creation.md): creating a new repository locally on the command-line _(recommended)_
+- [Initializing from the template](./docs/Initialization.md): creating a new repository with the [_Use this template_](https://github.com/JoshuaKGoldberg/template-typescript-node-package/generate) button on GitHub
+- [Migrating an existing repository](./docs/Migrate.md): adding this template's tooling on top of an existing repository
 
 ## Explainer
 

diff --git a/cspell.json b/cspell.json
@@ -15,6 +15,7 @@
 		"contributorsrc",
 		"conventionalcommits",
 		"execa",
+		"joshuakgoldberg",
 		"knip",
 		"lcov",
 		"markdownlintignore",

diff --git a/docs/Creation.md b/docs/Creation.md
@@ -0,0 +1,30 @@
+# Creating from the Terminal
+
+You can run `npx template-typescript-node-package` in your terminal to interactively create a new repository:
+
+```shell
+npx template-typescript-node-package
+```
+
+Then, go through the following two steps to set up required repository tooling on GitHub:
+
+1. Create two tokens in [repository secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) _(unless you chose to opt out of releases)_:
+   - `ACCESS_TOKEN`: A [GitHub PAT](https://github.com/settings/tokens/new) with _repo_ and _workflow_ permissions
+   - `NPM_TOKEN`: An [npm access token](https://docs.npmjs.com/creating-and-viewing-access-tokens/) with _Automation_ permissions
+2. Install two GitHub apps:
+   - [Codecov](https://github.com/marketplace/codecov) _(unless you chose to opt out of tests)_
+   - [Renovate](https://github.com/marketplace/renovate) _(unless you chose to opt out of renovate)_
+
+Your new repository will then be ready for development!
+Hooray! 🥳
+
+## Options
+
+You can explicitly provide some or all of the options the script would prompt for as command-line flags.
+See [Options.md](./Options.md).
+
+For example, running the creation script and skipping all APIs:
+
+```shell
+npx template-typescript-node-package --mode create --skip-contributors-data --skip-github-api
+```
diff --git a/docs/FAQs.md b/docs/FAQs.md
@@ -1,6 +1,6 @@
 # FAQs
 
-## Can I use &lt;insert tool here&gt with this template?
+## Can I use _(insert tool here)_ with this template?
 
 Yes!
 After you set up a repository, you can substitute in any tools you'd like.
@@ -20,3 +20,15 @@ This repository is meant to serve as a starter that includes all the general too
 Each of the included tools exists for a good reason and provides real value.
 
 If you don't want to use any particular tool, you can always remove it manually.
+
+### Which tools can't I remove?
+
+The following pieces of this template's tooling don't have options to be removed:
+
+- Linting with ESLint and `pnpm run lint`
+- GitHub repository metadata such as the code of conduct and issue templates
+- Prettier and `pnpm run format`
+- tsup and `pnpm run build`
+- TypeScript and `pnpm run tsc`
+
+If you have a strong desire to add an `--exclude-*` flag for any of them, please do [file a feature request](https://github.com/JoshuaKGoldberg/template-typescript-node-package/issues/new?assignees=&labels=type%3A+feature&projects=&template=03-feature.yml&title=%F0%9F%9A%80+Feature%3A+%3Cshort+description+of+the+feature%3E).
diff --git a/docs/Initialization.md b/docs/Initialization.md
@@ -0,0 +1,44 @@
+# Initializing from the Template
+
+As an alternative to [creating with `npx template-typescript-node-package`](./Creation.md), the [_Use this template_](https://github.com/JoshuaKGoldberg/template-typescript-node-package/generate) button on GitHub can be used to quickly create a new repository from the template.
+You can set up the new repository locally by cloning it and installing packages:
+
+```shell
+git clone https://github.com/YourUsername/YourRepositoryName
+cd YourRepositoryName
+pnpm i
+```
+
+> 💡 If you don't want to clone it locally, you can always [develop in a codespace](https://docs.github.com/en/codespaces/developing-in-codespaces/developing-in-a-codespace) instead.
+
+Once the repository's packages are installed, you can run `pnpm run initialize` to fill out your repository's details and install necessary packages.
+It will then remove itself and uninstall dependencies only used for initialization.
+
+```shell
+pnpm run initialize
+```
+
+Then, go through the following two steps to set up required repository tooling on GitHub:
+
+1. Create two tokens in [repository secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) _(unless you chose to opt out of releases)_:
+   - `ACCESS_TOKEN`: A [GitHub PAT](https://github.com/settings/tokens/new) with _repo_ and _workflow_ permissions
+   - `NPM_TOKEN`: An [npm access token](https://docs.npmjs.com/creating-and-viewing-access-tokens/) with _Automation_ permissions
+2. Install two GitHub apps:
+   - [Codecov](https://github.com/marketplace/codecov) _(unless you chose to opt out of tests)_
+   - [Renovate](https://github.com/marketplace/renovate) _(unless you chose to opt out of renovate)_
+
+Your new repository will then be ready for development!
+Hooray! 🥳
+
+## Options
+
+You can explicitly provide some or all of the options the script would prompt for as command-line flags.
+See [Options.md](./Options.md).
+
+`pnpm run initialize` will set `--mode` to `initialize`.
+
+For example, running the initialization script and skipping all APIs:
+
+```shell
+pnpm run initialize --skip-contributors-data --skip-github-api
+```
diff --git a/docs/InitializationFromTemplate.md b/docs/InitializationFromTemplate.md
diff --git a/docs/InitializationFromTerminal.md b/docs/InitializationFromTerminal.md
diff --git a/docs/Migration.md b/docs/Migration.md
@@ -1,6 +1,6 @@
 # Migrating an Existing Repository
 
-If you have an existing repository that you'd like to give the files from this repository, you can run `npx template-typescript-node-package` in it to "hydrate" its tooling with this template's.
+If you have an existing repository that you'd like to give the files from this repository, you can run `npx template-typescript-node-package` in it to "migrate" its tooling to this template's.
 
 ```shell
 npx template-typescript-node-package
@@ -11,48 +11,13 @@ npx template-typescript-node-package
 > You'll want to review each of the changes.
 > There will almost certainly be some incorrect changes you'll need to fix.
 
-## Values
+## Options
 
-Repository settings will be auto-filled from the repository's files if possible, but can be provided manually as well:
+You can explicitly provide some or all of the options the script would prompt for as command-line flags.
+See [Options.md](./Options.md).
 
-- `--author` _(`string`)_: e.g. `"Josh Goldberg"`
-- `--description` _(`string`)_: e.g. `"A quickstart-friendly TypeScript template with comprehensive formatting, linting, releases, testing, and other great tooling built-in. ✨"`
-- `--email` _(`string`)_: e.g. `"git@joshuakgoldberg.com"`
-- `--funding` _(`string`, optional)_: e.g. `"JoshuaKGoldberg"`
-- `--owner` _(`string`)_: e.g. `"JoshuaKGoldberg"`
-- `--repository` _(`string`)_: e.g. `"template-typescript-node-package"`
-- `--title` _(`string`)_: e.g. `"Template TypeScript Node Package"`
-
-For example, providing a `funding` value different from the `author`:
-
-```shell
-npx template-typescript-node-package --funding MyOrganization
-```
-
-The migration script by default will include all the features in this template.
-You can disable some of them on the command-line:
-
-- `releases` _(`boolean`)_: Whether to include automated package publishing
-- `unitTests` _(`boolean`)_: Whether to include unit tests with code coverage tracking
-
-```shell
-npx template-typescript-node-package --releases false --unitTests false
-```
-
-After the migration script finishes aligning your repository's contents to the templates, it will call the [Initialization](./Initialization.md) script as well.
-It will forward any values you provided or it inferred from the repository.
-
-### Skipping API Calls
-
-You can prevent the migration script from making some network-based changes using any or all of the following CLI flags:
-
-- `--skip-contributors` _(`boolean`)_: Skips detecting existing contributors with [`all-contributors-for-repository`](https://github.com/JoshuaKGoldberg/all-contributors-for-repository)
-- `--skip-github-api` _(`boolean`)_: Skips calling to GitHub APIs
-- `--skip-install` _(`boolean`)_: Skips installing all the new template packages with `pnpm`
+For example, running the migration script and skipping all APIs:
 
 ```shell
-npx template-typescript-node-package --skip-github-api --skip-install
+npx template-typescript-node-package --mode migrate --skip-contributors-data --skip-github-api
 ```
-
-> Tip: the `--skip-github-api` flag will cause all changes to be limited to your local repository.
-> That means you can test out the script with `npx template-typescript-node-package --skip-github-api`, then `git add -A; git reset --hard HEAD` to completely reset all changes.