docs: finalize audit remediation documentation updates

- Move programmatic API docs from README to docs/README_contributors.md
  (per user feedback: advanced feature, not for average users)
- Update TEST_COVERAGE_PLAN.md for consistency
  - Change objective 4 from "gh-pages-shell tests" to "behavioral tests"
  - Soften hard-coded test count (351 tests, see files for current count)
  - Add "Test Safety" success criterion (process.env preservation)
  - Clarify getRemoteUrl has 3 focused tests, not 6
- Remove emoji from documentation (unprofessional if overused)

All 8 audit weaknesses now addressed:
✅ Fixed dangerous process.env = {} pattern
✅ Consolidated redundant getRemoteUrl tests (6→3)
✅ Added error message assertions
✅ Added git config correctness verification
✅ Strengthened CI metadata tests (full .toBe() assertions)
✅ Updated CLAUDE.md testing policy (sensible .toContain() usage)
✅ Updated TEST_COVERAGE_PLAN.md consistency
✅ Added programmatic API documentation

All 351 tests passing.

Author: JohannesHoppe

TEST_COVERAGE_PLAN.md

@@ -4,7 +4,7 @@
 1. **Add critical missing tests** (silent failures, monkeypatch, real filesystem)
 2. **Refactor prepareOptions()** to enable intensive testing of each option
 3. **Export public types** for user extensibility
-4. **Complete gh-pages-shell tests** for v6 upgrade preparation
+4. **Complete gh-pages behavioral tests** (engine.gh-pages-behavior.spec.ts) for v6 upgrade preparation
 
 ---
 
@@ -215,14 +215,15 @@ All behavioral tests for gh-pages v3.2.3 are now complete and provide comprehens
 
 ## Success Criteria
 
-- **Test Count:** 213 → 353 tests (as of Nov 2024)
+- **Test Count:** 213 → 351 tests (comprehensive suite, see test files for current count)
 - **Coverage:** ✅ All critical paths tested (error callbacks, monkeypatch, file creation, getRemoteUrl, dotfiles)
 - **Refactoring:** ✅ prepareOptions split into 6 testable functions
 - **Public API:** ✅ Types exported via public_api.ts, TypeScript declarations enabled
 - **Upgrade Prep:** ✅ v3 git behavior documented in engine.gh-pages-behavior.spec.ts
-- **gh-pages/lib/git:** ✅ Internal API dependency intensively tested with 6 focused tests
-- **Dotfiles:** ✅ Tests now verify actual file list differences, not just that copy was called
+- **gh-pages/lib/git:** ✅ Internal API dependency intensively tested (3 focused tests verifying correctness)
+- **Dotfiles:** ✅ Tests verify actual file list differences (4 files with dotfiles, 3 without)
 - **Quality:** ✅ Zero regressions, all tests passing, zero 'any' types (HARD RULE compliant)
+- **Test Safety:** ✅ process.env properly preserved (PATH, HOME, etc.) across all test files
 
 ---
 

docs/README_contributors.md

@@ -189,6 +189,64 @@ npm run publish-to-npm
 npm dist-tag add angular-cli-ghpages@0.6.0-rc.0 next
 ```
 
+## Programmatic Usage
+
+For advanced use cases, `angular-cli-ghpages` can be used programmatically in Node.js scripts:
+
+```typescript
+import { deployToGHPages, defaults, Schema } from 'angular-cli-ghpages';
+
+// Deploy with custom options
+const options: Schema = {
+  ...defaults,
+  dir: 'dist/my-app/browser',
+  repo: 'https://github.com/user/repo.git',
+  message: 'Custom deploy message',
+  branch: 'gh-pages',
+  name: 'Deploy Bot',
+  email: 'bot@example.com'
+};
+
+// Simple logger implementation
+const logger = {
+  info: (msg: string) => console.log(msg),
+  warn: (msg: string) => console.warn(msg),
+  error: (msg: string) => console.error(msg),
+  debug: (msg: string) => console.debug(msg),
+  fatal: (msg: string) => console.error(msg)
+};
+
+try {
+  await deployToGHPages('dist/my-app/browser', options, logger);
+  console.log('Deployment successful!');
+} catch (error) {
+  console.error('Deployment failed:', error);
+}
+```
+
+### Available Types
+
+The package exports these TypeScript types for programmatic usage:
+
+- `Schema` - Complete options interface
+- `PreparedOptions` - Internal options after processing
+- `DeployUser` - User credentials type
+- `GHPages` - gh-pages library wrapper interface
+- `defaults` - Default configuration object
+
+### Advanced: Angular Builder Integration
+
+For custom Angular builders:
+
+```typescript
+import { angularDeploy } from 'angular-cli-ghpages';
+
+// Inside your custom builder
+const result = await angularDeploy(context, builderConfig, 'your-project-name');
+```
+
+**Note:** The CLI (`ng deploy`) remains the primary and recommended way to use this tool. Programmatic usage is considered advanced/experimental and may change between versions.
+
 ## Keeping track of all the forks
 
 [ngx-deploy-starter](https://github.com/angular-schule/ngx-deploy-starter/) and