docs: fix build target resolution precedence and add prerenderTarget examples

Complete remaining audit TODOs (D1, D2, PR1, PR2) to address documentation gaps:

1. D1 - CRITICAL FIX: Correct Build Target Resolution in CLAUDE.md
   - Previous docs incorrectly stated buildTarget was tried first
   - Code shows browserTarget || buildTarget (browserTarget has precedence)
   - Updated with correct precedence: prerenderTarget > browserTarget > buildTarget > default
   - Added implementation references (builder.ts:23-26, 45-50)

2. D2 - Clarify browserTarget in schema.json
   - Updated description to explain it's a legacy alias for buildTarget
   - Added precedence notes (browserTarget > buildTarget, prerenderTarget > both)
   - Recommends using buildTarget instead for new projects

3. PR1 - Add Comprehensive prerenderTarget Documentation (README.md)
   - New section explaining when to use prerenderTarget (SSG, Angular Universal)
   - Complete angular.json example showing prerender + deploy targets
   - Example workflow: ng deploy with prerenderTarget
   - Documented target precedence and interaction with --no-build

4. PR2 - CLI vs Builder Parameter Clarification (README_standalone.md)
   - New section explaining Builder-only parameters
   - Lists buildTarget, browserTarget, prerenderTarget, noBuild, baseHref
   - Example standalone workflows (build separately, then deploy)
   - Example SSG workflow (prerender, then deploy)
   - Clarifies why these don't work with npx angular-cli-ghpages

All tests pass (377 tests) with no regressions.

Addresses audit findings: documentation now matches actual code behavior and
provides complete examples for prerenderTarget usage.

Author: JohannesHoppe

CLAUDE.md

@@ -133,11 +133,18 @@ actions.ts (deploy function)
 
 ### Build Target Resolution
 
-**Important:** With Angular 17+, the build target resolution is complex due to different builder types. The code tries to guess the correct build target:
-
-1. First tries explicit `--build-target` option
-2. Falls back to `${project}:build:production`
-3. For prerendering: uses `prerenderTarget` or `${project}:prerender:production`
+**Important:** With Angular 17+, the build target resolution follows a strict precedence order. The builder evaluates targets in this order and uses the first one found:
+
+**Precedence (highest to lowest):**
+1. `prerenderTarget` - For SSG/prerendering builds (if specified, overrides all others)
+2. `browserTarget` - Legacy/alternative build target (if specified)
+3. `buildTarget` - Standard build target (if specified)
+4. Default - `${project}:build:production`
+
+**Implementation details:**
+- Static build target: `browserTarget || buildTarget || default` (see `src/deploy/builder.ts:23-26`)
+- Final target: `prerenderTarget || staticBuildTarget` (see `src/deploy/builder.ts:45-50`)
+- If `prerenderTarget` is set, it takes absolute precedence regardless of other targets
 
 Output directory resolution:
 - Checks `angular.json` for `outputPath`

README.md

@@ -259,6 +259,59 @@ NOW:
 ng deploy --build-target=test
 ```
 
+#### --prerender-target <a name="prerender-target"></a>
+
+- **optional**
+- Default: `undefined` (string)
+- Example:
+  - `ng deploy --prerender-target=myapp:prerender:production`
+
+For applications using Static Site Generation (SSG), you can specify a prerender target instead of a build target. This is useful when your Angular application uses the `@angular/ssr` package and you want to deploy the prerendered output.
+
+**When to use prerenderTarget:**
+- Your project has a `prerender` target configured in `angular.json`
+- You want to deploy statically prerendered HTML files
+- You're using Angular Universal or `@angular/ssr` for static prerendering
+
+**Example configuration in angular.json:**
+
+```json
+{
+  "projects": {
+    "my-app": {
+      "architect": {
+        "prerender": {
+          "builder": "@angular-devkit/build-angular:prerender",
+          "options": {
+            "routes": ["/", "/about", "/contact"]
+          },
+          "configurations": {
+            "production": {
+              "browserTarget": "my-app:build:production"
+            }
+          }
+        },
+        "deploy": {
+          "builder": "angular-cli-ghpages:deploy",
+          "options": {
+            "prerenderTarget": "my-app:prerender:production",
+            "baseHref": "/my-app/"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Now you can simply run:
+
+```sh
+ng deploy
+```
+
+**Target Precedence:** If `prerenderTarget` is specified, it takes precedence over both `buildTarget` and `browserTarget`. This command has no effect if the option `--no-build` is active.
+
 #### --no-build <a name="no-build"></a>
 
 - **optional**

docs/README_standalone.md

@@ -51,6 +51,45 @@ ionic build --prod -- --base-href=https://USERNAME.github.io/REPOSITORY_NAME/`
 npx angular-cli-ghpages --dir=www
 ```
 
+## Build Target Parameters (Angular Builder Only)
+
+The following parameters are **only available** when using `ng deploy` (Angular Builder integration) and are **not supported** by the standalone CLI:
+
+- `--build-target` / `buildTarget`
+- `--browser-target` / `browserTarget`
+- `--prerender-target` / `prerenderTarget`
+- `--no-build` / `noBuild`
+- `--base-href` / `baseHref` (only as a build option; use `ng build --base-href` instead)
+
+These parameters control Angular CLI's build process integration and automatic build triggering.
+
+**When using the standalone CLI** (`npx angular-cli-ghpages`):
+- You must **build your project separately** before deployment
+- Use `--dir` to specify the pre-built output directory
+- The standalone CLI will **not** trigger any build process
+
+**Example standalone workflow:**
+
+```bash
+# 1. Build your project first
+ng build --configuration=production --base-href=/my-app/
+
+# 2. Then deploy the built output
+npx angular-cli-ghpages --dir=dist/my-app/browser
+```
+
+**For SSG/Prerendering with standalone CLI:**
+
+```bash
+# 1. Prerender your project first
+ng run my-app:prerender:production
+
+# 2. Then deploy the prerendered output
+npx angular-cli-ghpages --dir=dist/my-app/browser
+```
+
+If you need automatic build integration, use `ng deploy` instead of the standalone CLI. See the [main README](../README.md) for Angular Builder usage.
+
 ## Extra
 
 For your convenience, the command will recognize the [environment variable](https://docs.travis-ci.com/user/environment-variables/#Defining-Variables-in-Repository-Settings) `GH_TOKEN` and will replace this pattern in the `--repo` string.

src/deploy/schema.json

@@ -13,7 +13,7 @@
     },
     "browserTarget": {
       "type": "string",
-      "description": "A named build target, as specified in the `configurations` section of angular.json. Each named target is accompanied by a configuration of option defaults for that target. This is equivalent to calling the command `ng build --configuration=XXX`."
+      "description": "Legacy alias for buildTarget. A named build target, as specified in the `configurations` section of angular.json. Note: browserTarget takes precedence over buildTarget if both are specified, but prerenderTarget takes precedence over both. Most users should use buildTarget instead."
     },
     "prerenderTarget": {
       "type": "string",