docs: updated concurrency flag

docs/cli/build.md

@@ -20,7 +20,7 @@ The `build` command transforms your Markdown content into a static HTML website.
 | `--baseDir`       |           | Set a base directory for the site (e.g. for GitHub Pages) | `/`               |
 | `--remoteDevHost` |           | The hostname to use for the development server            | `localhost`       |
 | `--bundleInfo`    |           | Output a JSON file with bundle size information           | `false`           |
-| `--concurrency`   |           | Number of worker threads to use for building              | CPU core count    |
+| `--concurrency`   | `-c`      | Number of worker threads to use for building              | CPU core count    |
 
 ## Examples
 

docs/cli/index.md

@@ -27,6 +27,18 @@ You can run the CLI using `npx quartz`.
 - [[cli/plugin|plugin]]: Install, add, remove, prune, and configure plugins. Use `plugin install` with flags for lockfile/config sync, updates, and checks.
 - [[cli/tui|tui]]: Use a terminal interface to manage plugins and layout.
 
+## Global Flags
+
+These flags are accepted by every Quartz command:
+
+| Flag            | Shorthand | Description                                                                                             | Default        |
+| --------------- | --------- | ------------------------------------------------------------------------------------------------------- | -------------- |
+| `--directory`   | `-d`      | The directory containing your Quartz project                                                            | `content`      |
+| `--verbose`     | `-v`      | Enable detailed logging for debugging                                                                   | `false`        |
+| `--concurrency` | `-c`      | Max parallel workers for operations that run in parallel (e.g. `build`, `plugin install`, `plugin add`) | CPU core count |
+
+Commands that don't perform parallel work accept `-c` as a no-op, so it's always safe to pass. See [[cli/build#Performance Tuning|build]] and [[cli/plugin#Installing on low-end hardware|plugin]] for practical examples.
+
 ## Help and Versioning
 
 To see a full list of available flags for any command, use the `--help` flag.

docs/cli/plugin.md

@@ -44,6 +44,9 @@ Local plugins are symlinked into `.quartz/plugins/`, so any changes you make to
 
 When a branch is specified, it is stored in the lockfile. All subsequent commands (`install`, `prune`) will respect that branch automatically. Use `install --latest` to fetch the latest commit from that branch.
 
+> [!tip]
+> `plugin add` also accepts `--concurrency` / `-c` to limit how many remote repositories are cloned and built at the same time. This is the same flag documented under [[#install]] and is useful when adding several plugins at once on low-end hardware.
+
 ### remove
 
 Remove an installed plugin.
@@ -66,6 +69,7 @@ npx quartz plugin install
 - `--latest`: Fetch the latest version of plugins from their remote sources instead of using the version in the lockfile.
 - `--clean`: Skip existing directories and perform a fresh installation.
 - `--dry-run`: Preview the changes without actually installing or removing any files.
+- `--concurrency`, `-c`: Maximum number of plugins to clone, fetch, and build in parallel. Defaults to the number of CPU cores. Lower this (e.g. `-c 1` or `-c 2`) on memory- or CPU-constrained machines where the default parallelism causes failures, OOMs, or hangs. See [[#Installing on low-end hardware]] below.
 
 #### Positional Arguments
 
@@ -134,6 +138,26 @@ To keep your plugins fresh:
 npx quartz plugin install --latest
 ```
 
+### Installing on low-end hardware
+
+By default, `plugin install` and `plugin add` clone, fetch, and build plugins in parallel across all your CPU cores. On memory-constrained machines (low-end laptops, Raspberry Pi, small VPS instances, restrictive CI runners) this can exhaust RAM or overwhelm the system because each worker may kick off its own `npm install` / `npm run build` at the same time.
+
+If `plugin install` fails, hangs, or OOMs on your machine, lower the concurrency with `--concurrency` / `-c`:
+
+```shell
+# Install one plugin at a time (safest, slowest)
+npx quartz plugin install --latest -c 1
+
+# Two at a time — usually a good balance on 4 GB machines
+npx quartz plugin install --latest --concurrency 2
+```
+
+The same flag works on `plugin add` and the other plugin subcommands that perform parallel work:
+
+```shell
+npx quartz plugin add github:quartz-community/some-plugin -c 1
+```
+
 ### Managing Configuration
 
 If you want to change a plugin setting without opening the YAML file:

docs/troubleshooting.md

@@ -26,6 +26,8 @@ Try increasing concurrency:
 
 ```bash
 npx quartz build --concurrency 8
+# or the shorthand:
+npx quartz build -c 8
 ```
 
 The default uses all available CPU cores. If you're on a memory-constrained environment (CI), reducing concurrency may actually help.
@@ -60,6 +62,28 @@ This means the plugin is referenced in `quartz.ts` but not installed. Either:
 - Install it: `npx quartz plugin add github:quartz-community/plugin-name`
 - Or remove the reference from `quartz.ts`
 
+### `plugin install` hangs, OOMs, or fails on low-end hardware
+
+By default, `npx quartz plugin install` clones, fetches, and builds plugins in parallel across all your CPU cores. Each parallel worker may run its own `npm install` and `npm run build`, which is memory-intensive. On low-end laptops, Raspberry Pi, small VPS instances, or restrictive CI runners this can exhaust RAM, trigger the OOM killer, or make the system appear to hang.
+
+Lower the parallelism with `--concurrency` / `-c`:
+
+```bash
+# Install one plugin at a time (safest, slowest)
+npx quartz plugin install --latest -c 1
+
+# Two at a time — usually works on 4 GB machines
+npx quartz plugin install --latest --concurrency 2
+```
+
+The same flag works for `plugin add` and the deprecated aliases (`plugin update`, `plugin restore`, `plugin check`, `plugin resolve`):
+
+```bash
+npx quartz plugin add github:quartz-community/some-plugin -c 1
+```
+
+If `plugin install` consistently fails near the same plugin with `-c 1`, the issue is likely with that specific plugin's build, not with concurrency — try running `--verbose` to get detailed error output, and check the plugin's own repository for known issues.
+
 ## Content Issues
 
 ### Notes not showing up