chore: sync 1.2.2 onto main + CI/CD docs

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "1.2.1"
+  ".": "1.2.2"
 }

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to leash-secrets will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+
+## [1.2.2](https://github.com/FasterApiWeb/leash-secrets/compare/leash-secrets-v1.2.1...leash-secrets-v1.2.2) (2026-07-10)
+
+### Maintenance
+
+* release 1.2.2
+
 ## [1.2.1](https://github.com/FasterApiWeb/leash-secrets/compare/leash-secrets-v1.2.0...leash-secrets-v1.2.1) (2026-07-09)
 
 

CITATION.cff

@@ -12,8 +12,8 @@ authors:
 repository-code: https://github.com/FasterApiWeb/leash-secrets
 url: https://fasterapiweb.github.io/leash-secrets
 license: MIT
-version: 1.2.1
-date-released: "2026-07-09"
+version: 1.2.2
+date-released: "2026-07-10"
 keywords:
   - secret-detection
   - security

CONTRIBUTING.md

@@ -93,20 +93,27 @@ Quick path: **Actions → Release Draft (auto-bumps) → Publish draft → npm**
 
 ### One-time secrets
 
+Prefer **org-level** secrets (not a personal PAT):
+
 | Secret | Purpose |
 |--------|---------|
 | `NPM_TOKEN` | Publish to npm (**required** to ship) |
-| `RELEASE_TOKEN` or `RELEASE_APP_*` | Recommended for Release Draft push to protected `main` (else `GITHUB_TOKEN` may be blocked) |
+| `RELEASE_APP_ID` / `RELEASE_APP_PRIVATE_KEY` / `RELEASE_APP_INSTALLATION_ID` | Org GitHub App so Release Draft can push bumps to protected `main` |
 | `VSCE_PAT` | VS Code marketplace *(deferred)* |
 
-Details: [ci-cd.md — Secrets](docs/contributing/ci-cd.md#secrets-needed).
+Do **not** use a personal `RELEASE_TOKEN` if the App is set up. Full steps (create App, install, secrets, ruleset bypass): [ci-cd.md — Org GitHub App](docs/contributing/ci-cd.md#org-github-app-for-release-draft-recommended). **No CI workflow file changes** are required for the App.
+
+### After merge to `main`
+
+Automatic: **CI** (always) → **Validate Patterns** / **Deploy Docs** (only if paths match) → **Release** (legacy; ignore).  
+To ship: **Release Draft** → Publish draft → **Publish npm**. Details: [ci-cd.md — After a merge](docs/contributing/ci-cd.md#after-a-merge-to-main--what-runs-in-order).
 
 ### Release checklist (short)
 
 1. **Actions → Release Draft → Run** (`patch` / `minor` / `major`) — bumps version on `main` if needed, creates draft  
 2. **Releases → Publish** the draft → **Publish npm** runs (skips if version already on npm)  
 
-If the draft push fails: add `RELEASE_TOKEN` (admin PAT / bypass) and re-run.  
+If the draft push fails: finish org App + ruleset bypass, then re-run.  
 If you only need npm: **Actions → Publish npm → Run workflow**.
 ## PR Guidelines
 

docs/contributing/ci-cd.md

@@ -13,7 +13,8 @@ You open a PR
 
 Push lands on main
     → CI again
-    → Deploy Docs
+    → Deploy Docs (if docs/** changed)
+    → Validate Patterns (if patterns/** changed)
     → Release (release-please)  ← legacy; usually ignore
 
 When you want to ship a version
@@ -40,42 +41,133 @@ Release Draft (auto-bump)  →  draft tag/assets  →  Publish draft  →  npm
 
 | Workflow | When it runs | Purpose |
 |----------|--------------|---------|
-| **CI** | Every PR + every push to `main` | Quality gate: Node 18/20/22 tests, shell syntax, hygiene (incl. `install.sh` ↔ `package.json` version), dogfood scan |
-| **Validate Patterns** | PRs/pushes that touch `patterns/` | Pattern JSON / fixture validation |
-| **Deploy Docs** | Push to `main` | MkDocs → GitHub Pages |
-| **Release** (release-please) | Push to `main` | **Legacy.** Tries to manage release PRs/tags. Org often blocks Actions from opening PRs — prefer **Release Draft** |
-| **Release Draft** | **Manual** (`workflow_dispatch`) | You pick patch/minor/major → bumps `package.json` / `install.sh` / etc. if needed → **draft** `leash-secrets-vX.Y.Z` + assets |
+| **CI** | Every PR + every push to `main` (+ manual) | Quality gate: Node 18/20/22 tests, shell syntax, hygiene (incl. `install.sh` ↔ `package.json` version), dogfood scan |
+| **Validate Patterns** | PRs/pushes that touch `patterns/` (or related tests/scripts) | Pattern JSON / fixture validation |
+| **Deploy Docs** | Push to `main` that touches `docs/**` (or MkDocs config) (+ manual) | MkDocs → GitHub Pages |
+| **Release** (release-please) | Push to `main` (+ manual) | **Legacy.** Tries to manage release PRs/tags. Org often blocks Actions from opening PRs — prefer **Release Draft** |
+| **Release Draft** | **Manual** (`workflow_dispatch`) | You pick patch/minor/major → bumps version files if needed → **draft** `leash-secrets-vX.Y.Z` + assets |
 | **Publish npm** | Manual, **or** when a draft release is **published** | `npm publish --provenance` (succeeds as no-op if version already on npm) |
 
 Workflow files live under [`.github/workflows/`](https://github.com/FasterApiWeb/leash-secrets/tree/main/.github/workflows).
 
+## After a merge to `main` — what runs, in order
+
+Merging a PR (or landing a commit on `main`) does **not** publish npm. These workflows fire automatically from the push:
+
+| Order | Workflow | Runs when? | What it does | You should… |
+|-------|----------|------------|--------------|-------------|
+| 1 | **CI** | Always on push to `main` | Re-runs the full test matrix on `main` | Wait for green. Required status check for future PRs. |
+| 2 | **Validate Patterns** | Only if the merge touched `patterns/**`, `tests/**`, or `scripts/check-patterns.js` | Extra pattern/fixture checks | Confirm green if it ran; otherwise ignore. |
+| 3 | **Deploy Docs** | Only if the merge touched `docs/**`, `mkdocs.yml`, `requirements.txt`, or the docs workflow | Builds MkDocs and deploys GitHub Pages | Confirm the site updated if you changed docs. |
+| 4 | **Release** (release-please) | Always on push to `main` | Legacy release-please attempt | **Ignore** unless debugging. Prefer **Release Draft** to ship. |
+
+Nothing else is required for a normal feature/fix merge.
+
+### When you want to ship a version (manual, after `main` is green)
+
+Do these **in order** — they are not automatic on merge:
+
+| Order | Action | Workflow / UI | Purpose |
+|-------|--------|---------------|---------|
+| 1 | Run **Release Draft** | Actions → Release Draft → patch/minor/major | Bumps version on `main` (needs org GitHub App; see below), creates **draft** `leash-secrets-vX.Y.Z` |
+| 2 | Review & **Publish** the draft | Releases → open draft → Publish | Makes the GitHub Release public; fires the next step |
+| 3 | **Publish npm** | Runs automatically on publish (or Actions → Publish npm) | Publishes `leash-secrets@X.Y.Z` (skips if already on npm) |
+
+Optional: **Publish npm** alone if the GitHub release/tag already exists and you only need the registry.
+
 ## Secrets needed
 
-Add under **Settings → Secrets and variables → Actions**.
+Prefer **org-level** secrets (FasterApiWeb → Settings → Secrets and variables → Actions → Organization secrets) so nothing is tied to a personal account. Grant them to `leash-secrets` (and any other repos that release the same way).
 
 | Secret | Required? | Used by | How to create |
 |--------|-----------|---------|---------------|
 | `NPM_TOKEN` | **Yes** (to publish) | Publish npm | [npmjs.com](https://www.npmjs.com) → Access Tokens → Granular token with **Read and Write** + **Bypass 2FA for publish** |
-| `RELEASE_TOKEN` | Optional | Release Draft | PAT with contents write; otherwise `GITHUB_TOKEN` is used |
-| `RELEASE_APP_ID` / `RELEASE_APP_PRIVATE_KEY` / `RELEASE_APP_INSTALLATION_ID` | Optional | Release Draft | GitHub App install token (same pattern as fork-shepherd releases) |
+| `RELEASE_APP_ID` / `RELEASE_APP_PRIVATE_KEY` / `RELEASE_APP_INSTALLATION_ID` | **Recommended** | Release Draft | Org GitHub App (see below). Preferred over a personal PAT. |
+| `RELEASE_TOKEN` | Avoid | Release Draft | Personal PAT — not needed if the App is configured |
 | `VSCE_PAT` | Deferred | VS Code extension publish | Azure DevOps PAT with **Marketplace → Manage** |
 
-### Actions policy
+### Org GitHub App for Release Draft (recommended)
+
+`GITHUB_TOKEN` cannot push to protected `main`. A **personal** `RELEASE_TOKEN` works but is tied to one human. Use an **org-owned GitHub App** instead. **No workflow file changes are required** — `release-draft.yml` already reads these secrets.
+
+#### 1. Create the App (org owner)
+
+1. Open [github.com/organizations/FasterApiWeb/settings/apps/new](https://github.com/organizations/FasterApiWeb/settings/apps/new)
+2. Fill in:
+   - **GitHub App name:** e.g. `FasterApiWeb Release` (must be unique on GitHub)
+   - **Homepage URL:** `https://github.com/FasterApiWeb` (or this repo’s URL)
+   - **Webhook:** uncheck **Active**
+3. **Repository permissions:**
+   - **Contents** → **Read and write**
+   - **Metadata** → **Read-only** (usually already set)
+4. Leave **Account permissions** at **No access**
+5. **Where can this GitHub App be installed?** → **Only on this account**
+6. Click **Create GitHub App**
+
+#### 2. Generate the private key
+
+1. On the App settings page → **Private keys** → **Generate a private key**
+2. Download the `.pem` (paste into a secret once; never commit it)
+3. Note the **App ID** under **About** (digits only)
+
+#### 3. Install the App on the org
+
+1. App settings → **Install App** (or open the App’s install URL)
+2. Choose **FasterApiWeb**
+3. **Only select repositories** → **`leash-secrets`** (or all repos if you reuse it)
+4. **Install**
 
-Org/repo must allow Marketplace actions:
+#### 4. Copy the Installation ID
 
-`Settings → Actions → General → Allow all actions and reusable workflows`
+1. [Org → Settings → GitHub Apps → Installed GitHub Apps](https://github.com/organizations/FasterApiWeb/settings/installations) → **Configure** next to the App
+2. URL looks like:  
+   `https://github.com/organizations/FasterApiWeb/settings/installations/XXXXXXXX`  
+   **`XXXXXXXX`** = `RELEASE_APP_INSTALLATION_ID`
 
-If CI shows `startup_failure` with zero jobs, the org is likely set to `local_only`.
+#### 5. Add org Actions secrets
+
+1. [Organization secrets](https://github.com/organizations/FasterApiWeb/settings/secrets/actions) → **New organization secret** for each:
+
+   | Name | Value |
+   |------|--------|
+   | `RELEASE_APP_ID` | App ID (number) |
+   | `RELEASE_APP_PRIVATE_KEY` | Full `.pem` contents (including `BEGIN` / `END` lines) |
+   | `RELEASE_APP_INSTALLATION_ID` | Installation ID (number) |
+
+2. **Repository access** → **Selected repositories** → add **`leash-secrets`**
+
+Do **not** add a personal `RELEASE_TOKEN` if the App is configured.
+
+#### 6. Bypass rulesets for the App (required)
+
+Secrets alone are not enough — branch rules still block pushes unless the App is on the bypass list.
+
+1. Repo [Rules](https://github.com/FasterApiWeb/leash-secrets/rules) (or org rulesets) → open the ruleset that targets `main`
+2. **Bypass list** → **Add bypass** → **GitHub Apps** → select your Release App
+3. Bypass mode: **Always allow** (or **Exempt**)
+4. Save
+
+Also check classic **Settings → Branches** protection if it still applies.
+
+#### 7. Actions policy
+
+Org or repo: **Settings → Actions → General** → **Allow all actions and reusable workflows**  
+(needed for `actions/create-github-app-token@v2`)
+
+#### 8. Verify
+
+1. **Actions → Release Draft → Run workflow** (`main`, `patch`; optional `dry_run` first)
+2. Log step **Resolve release token** should say: `Using GitHub App installation token`
+3. On a real run, the bump commit should land on **`main`** (not `release/v*`)
+
+Release Draft token preference: App → `RELEASE_TOKEN` → `GITHUB_TOKEN`.
 
 ## Day-to-day (features / fixes)
 
 1. Open a PR → wait for **CI** (and **Validate Patterns** if you changed patterns).
 2. Merge when green (squash).
-3. **Deploy Docs** updates the site on `main`.
-4. Ignore **Release** (release-please) unless debugging it.
-
-No npm publish happens on normal merges.
+3. On `main`: **CI** always; **Deploy Docs** / **Validate Patterns** only if paths match; ignore **Release**.
+4. No npm publish on normal merges.
 
 ## How to ship a version
 
@@ -92,7 +184,7 @@ The workflow:
 - If `package.json` is behind, **bumps** `package.json`, `install.sh`, `CITATION.cff`, `vscode-extension/package.json`, manifest, and `CHANGELOG.md`, then **pushes** `chore: release X.Y.Z` to `main`
 - Creates a **draft** release `leash-secrets-vX.Y.Z` + assets
 
-If the push fails (branch protection), add `RELEASE_TOKEN` (admin PAT that can push to `main` / bypass rulesets) or allow the GitHub Actions app to bypass the main ruleset, then re-run.
+If the push fails (branch protection), finish the org GitHub App + ruleset bypass steps above, then re-run. Without that, the workflow falls back to a `release/vX.Y.Z` branch (merge that to `main` manually, then delete the branch).
 
 ### 2. Publish the draft
 
@@ -107,6 +199,7 @@ Result: **Publish npm** runs and publishes `leash-secrets@X.Y.Z` (or no-ops if t
 **Actions → Publish npm → Run workflow** — publishes whatever version is on the checked-out ref; skips cleanly if already published.
 
 Optional local prep (still supported): `bash scripts/prepare-release.sh` if you prefer a version-bump PR before Release Draft.
+
 ## Branch protection (maintainer note)
 
 `main` requires PRs and the CI status checks. Required **approving** reviews are set to **0** so the sole maintainer can merge their own PRs (GitHub never counts self-approvals). CI must still be green. Revisit if more maintainers join.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "leash-secrets",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Keep your secrets on a leash — AI agent skill that catches exposed API keys, tokens, and credentials before they hit your codebase",
   "main": "src/index.js",
   "bin": {

scripts/install.sh

@@ -5,7 +5,7 @@ set -euo pipefail
 # leash-secrets installer — macOS · Linux · WSL · Git Bash
 # ──────────────────────────────────────────
 
-VERSION="1.2.1"
+VERSION="1.2.2"
 REPO="FasterApiWeb/leash-secrets"
 RAW="https://raw.githubusercontent.com/$REPO/main"
 

vscode-extension/package.json

@@ -2,7 +2,7 @@
   "name": "leash-secrets-vscode",
   "displayName": "Leash Secrets — Secret Scanner",
   "description": "Inline warnings for exposed API keys, tokens, and credentials. 71 patterns across 11 provider categories.",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "publisher": "FasterApiWeb",
   "license": "MIT",
   "icon": "icon.png",