docs: update CLAUDE.md with deprecation enforcement details

Add comprehensive documentation from audit remediation session:

- Schema artifact sync process (schema.json → schema.d.ts → dist/)
- Detailed deprecation handling policy with JSON Schema flags
- Audit checklist for verifying deprecated options aren't promoted
- Build process lifecycle (prebuild/build/postbuild) explanation
- npm scripts compatibility (works with ignore-scripts=true)
- Target precedence: internal vs user-facing documentation
- Complete test file inventory with categorization
- Test environment requirements and process.env preservation

All new knowledge from the documentation honesty audit session.

Author: JohannesHoppe

CLAUDE.md

@@ -19,10 +19,18 @@ cd src
 npm run build
 ```
 Compiles TypeScript to JavaScript and copies necessary files to `dist/`. The build process:
-1. Cleans the `dist` directory
-2. Generates TypeScript types from `deploy/schema.json`
-3. Compiles TypeScript using `tsconfig.build.json`
-4. Copies metadata files (builders.json, collection.json, etc.) to `dist/`
+1. **`prebuild`**: Cleans the `dist` directory and regenerates `deploy/schema.d.ts` from `deploy/schema.json`
+2. **`build`**: Compiles TypeScript using `tsconfig.build.json`
+3. **`postbuild`**: Copies metadata files (builders.json, collection.json, schema.json, etc.) to `dist/`
+
+**Important:** After editing `deploy/schema.json`, you MUST run `npm run build` to regenerate `schema.d.ts` and sync `dist/deploy/schema.json`. The build artifacts are gitignored (as they should be), so they won't be committed.
+
+**Schema Artifact Sync:**
+- `src/deploy/schema.json` - Source of truth (edit this)
+- `src/deploy/schema.d.ts` - Generated TypeScript types (auto-generated via `json-schema-to-typescript`)
+- `src/dist/deploy/schema.json` - Distributed schema (copied during build)
+
+**npm scripts compatibility:** This project does NOT use lifecycle hooks (`prepare`, `postinstall`, etc.). All build steps are manual via `npm run <script>`. Safe to use with `ignore-scripts=true` in global `.npmrc` for security.
 
 ### Test
 ```bash
@@ -135,12 +143,19 @@ actions.ts (deploy function)
 
 **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):**
+**Internal Implementation Precedence (what the code actually does):**
 1. `prerenderTarget` - For SSG/prerendering builds (if specified, overrides all others)
-2. `browserTarget` - Legacy/alternative build target (if specified)
+2. `browserTarget` - **DEPRECATED** legacy option (if specified, takes precedence over buildTarget for backward compatibility)
 3. `buildTarget` - Standard build target (if specified)
 4. Default - `${project}:build:production`
 
+**User-Facing Precedence (what we tell users in README.md):**
+1. `prerenderTarget` (if specified) — highest priority
+2. `buildTarget`
+3. Default: `${project}:build:production` if none specified
+
+**Note:** `browserTarget` is deliberately HIDDEN from user-facing documentation per deprecation policy, even though it still works internally for backward compatibility.
+
 **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`)
@@ -205,13 +220,49 @@ Angular CLI does NOT rename kebab-case to camelCase for boolean flags with "no"
 - **DO NOT promote deprecated options** in examples or main sections
 - Hide compatibility-only options from users: `browserTarget`, `noSilent`
 - Only show options users should actually use
+- When documenting target precedence, omit deprecated options entirely
 
 **Where Deprecated Options Belong**:
-- ✅ `schema.json` with `"deprecated": true` flag
+- ✅ `schema.json` with `"deprecated": true` and `"x-deprecated": "message"` fields
 - ✅ CLAUDE.md (for contributors)
 - ✅ BREAKING CHANGES sections (when explaining migrations)
-- ❌ Configuration File examples
-- ❌ Main Deployment Options sections
+- ✅ Code comments explaining backward compatibility
+- ❌ Configuration File examples in README
+- ❌ Main Deployment Options sections in README
+- ❌ Precedence explanations in user-facing docs
+
+**Schema Deprecation Flags:**
+- `"deprecated": true` - JSON Schema Draft 2019-09 standard flag (Angular CLI recognizes this)
+- `"x-deprecated": "message"` - Angular CLI custom extension for deprecation messages
+- `"description": "DEPRECATED: ..."` - Human-readable description prefix
+
+**Example:**
+```json
+"browserTarget": {
+  "type": "string",
+  "deprecated": true,
+  "x-deprecated": "Use buildTarget instead. Kept for backwards compatibility.",
+  "description": "DEPRECATED: Use buildTarget instead. Legacy alias kept for backwards compatibility only."
+}
+```
+
+**Auditing for Deprecated Option Mentions:**
+
+Run these checks before releases:
+```bash
+# Check README for browserTarget mentions (should be zero in user-facing sections)
+grep -n "browserTarget" README.md
+
+# Check README for noSilent mentions (should be zero)
+grep -n "noSilent" README.md
+
+# Verify schema.json has deprecation flags
+grep -A3 "browserTarget" src/deploy/schema.json
+```
+
+**Current deprecated options:**
+- `browserTarget` - Replaced by `buildTarget`, still works for compatibility
+- `noSilent` - No longer needed, parameter is ignored with warning
 
 **Avoid Test Count Bragging**:
 - Don't include specific test counts in documentation
@@ -221,18 +272,44 @@ Angular CLI does NOT rename kebab-case to camelCase for boolean flags with "no"
 ## Testing Strategy
 
 Tests use Jest and are located alongside source files with `.spec.ts` extension:
+
+**Deployment & Integration:**
 - `deploy/actions.spec.ts` - Deployment action tests
-- `engine/engine.spec.ts` - Core engine tests
+- `deploy/builder.spec.ts` - Builder integration tests
 - `ng-add.spec.ts` - Schematic tests
+
+**Core Engine:**
+- `engine/engine.spec.ts` - Core engine tests (includes prepareOptions, monkeypatch, error handling)
+- `engine/engine.prepare-options-helpers.spec.ts` - Intensive tests for option preparation helpers (getRemoteUrl, token injection, CI metadata)
+- `engine/engine-filesystem.spec.ts` - Real filesystem tests (.nojekyll, CNAME, 404.html creation)
+- `engine/engine.gh-pages-behavior.spec.ts` - gh-pages v3.2.3 behavioral baseline (dotfiles, file lists)
+- `engine/engine.gh-pages-integration.spec.ts` - gh-pages option pass-through and API integration
+
+**Parameter Testing:**
 - `parameter-tests/parameter-passthrough.spec.ts` - Parameter transformation tests
 - `parameter-tests/edge-cases.spec.ts` - Edge case and boundary tests
 - `parameter-tests/cli-e2e.spec.ts` - End-to-end standalone CLI testing
 - `parameter-tests/builder-integration.spec.ts` - Angular Builder integration tests
 - `parameter-tests/build-target.spec.ts` - Build target resolution matrix (buildTarget/browserTarget/prerenderTarget/noBuild)
+- `parameter-tests/builder-passthrough.spec.ts` - Builder option pass-through tests
+- `parameter-tests/pr-186-commander-defaults.spec.ts` - Commander v3 compatibility and default behavior
+
+**Environment & Prerequisites:**
 - `test-prerequisites.spec.ts` - Environment validation (git availability, repository setup, origin remote)
 
+**Public API:**
+- `public-api.spec.ts` - Public API exports validation
+
+**Commander Fork (CLI parsing):**
+- `commander-fork/test/*.spec.ts` - Tests for commander v3 compatibility fork
+
 Snapshot tests are stored in `__snapshots__/` directory.
 
+**Test Environment Requirements:**
+- Tests must run from a git clone with `origin` remote configured
+- See `test-prerequisites.spec.ts` for validation details
+- All tests use `originalEnv` pattern to preserve and restore `process.env`
+
 ### Testing Philosophy: Explicit Assertions
 
 **Prefer precise assertions with `.toBe()` for scalar values, but allow `.toContain()` where appropriate.**