@mcptoolshop/mcpt-publishing 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 MCP Tool Shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,223 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop/mcpt-publishing/main/logo.png" alt="mcpt-publishing logo" width="520" />
+</p>
+
+<h1 align="center">mcpt-publishing</h1>
+
+<p align="center">
+  <b>A human-first publishing house for your repos.</b><br/>
+  Audit, fix, and publish to npm/NuGet/PyPI/GHCR with receipts you can verify.
+</p>
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop/mcpt-publishing/releases"><img alt="GitHub release" src="https://img.shields.io/github/v/release/mcp-tool-shop/mcpt-publishing?style=flat-square"></a>
+  <a href="https://www.npmjs.com/package/@mcptoolshop/mcpt-publishing"><img alt="npm" src="https://img.shields.io/npm/v/@mcptoolshop/mcpt-publishing?style=flat-square"></a>
+  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square"></a>
+</p>
+
+---
+
+## What it is
+
+**mcpt-publishing** is a portable "publishing layer" that sits between your repos and public registries.
+
+It answers the annoying questions humans actually have:
+
+- *Are my registry pages stale or embarrassing?*
+- *Do tags/releases match what's published?*
+- *Which packages need a metadata refresh right now?*
+- *Can I publish safely, repeatedly, and prove what happened?*
+
+Every run produces **receipts**: immutable JSON artifacts with SHA-256 hashes, commit SHAs, and links to registry pages and GitHub releases.
+
+---
+
+## Who this is for
+
+**For you if...**
+
+- You publish to **npm and/or NuGet** and your pages drift over time (they do).
+- You want a single place to enforce "registry truth" (versions, tags, URLs, READMEs, icons).
+- You want automation that's safe: **plans, PRs, receipts**, and no surprise pushes.
+
+**Not for you if...**
+
+- You want a marketing site or spotlight engine (this is the plumbing).
+- You want a monolithic CI framework (this is a small toolkit you can embed anywhere).
+
+---
+
+## 60-second quickstart
+
+### Install
+
+```bash
+npm i -D @mcptoolshop/mcpt-publishing
+```
+
+### Initialize
+
+```bash
+npx mcpt-publishing init
+```
+
+This scaffolds:
+
+- `publishing.config.json`
+- `profiles/` (where repos/packages are declared)
+- `reports/` and `receipts/` output folders
+
+### Run an audit
+
+```bash
+npx mcpt-publishing audit
+```
+
+Outputs:
+
+- `reports/latest.md` (human-readable)
+- `reports/latest.json` (machine-readable)
+- a receipt under `receipts/`
+
+---
+
+## Core commands
+
+### `mcpt-publishing audit`
+
+Checks your publishing surfaces across enabled registries.
+
+```bash
+npx mcpt-publishing audit
+npx mcpt-publishing audit --json
+```
+
+### `mcpt-publishing plan`
+
+Generates a safe plan to fix drift (no network writes). *(coming soon)*
+
+```bash
+npx mcpt-publishing plan
+npx mcpt-publishing plan --repo mcp-tool-shop-org/soundboard-maui
+```
+
+### `mcpt-publishing apply`
+
+Applies the plan as PRs (never pushes to main). *(coming soon)*
+
+```bash
+npx mcpt-publishing apply
+npx mcpt-publishing apply --batch
+```
+
+### `mcpt-publishing publish`
+
+Publishes to a target registry using tokens/secrets. *(coming soon)*
+
+```bash
+npx mcpt-publishing publish --repo mcp-tool-shop-org/soundboard-maui --target npm
+npx mcpt-publishing publish --repo mcp-tool-shop-org/Soundboard.Client --target nuget
+```
+
+### `mcpt-publishing providers`
+
+Shows enabled providers and required env vars.
+
+```bash
+npx mcpt-publishing providers
+```
+
+### `mcpt-publishing verify-receipt`
+
+Validates receipts (schema + immutability). *(coming soon)*
+
+```bash
+npx mcpt-publishing verify-receipt receipts/publish/...
+```
+
+---
+
+## Optional: assets plugin (logos + images)
+
+Core is zero-dependency. Visual updates (logos, icons, OG images) are handled by an optional plugin: *(coming soon)*
+
+```bash
+npm i -D @mcptoolshop/mcpt-publishing-assets
+npx mcpt-publishing assets doctor
+npx mcpt-publishing assets logo --repo mcp-tool-shop-org/mcpt
+```
+
+This plugin depends on `sharp` and is kept separate so installs remain fast and reliable.
+
+---
+
+## Configuration
+
+### `publishing.config.json`
+
+Controls paths, enabled registries, and GitHub "glue" behaviors (attach receipts to releases, update pinned health issue, etc.).
+
+### `profiles/`
+
+Each profile declares:
+
+- the repo
+- the packages it publishes
+- target registries (npm/nuget/pypi/ghcr)
+- any special rules (tag prefix, monorepo paths, etc.)
+
+Schemas live in:
+
+- `schemas/profile.schema.json`
+- `schemas/receipt.schema.json`
+
+Contract + phases: `docs/CONTRACT.md`
+
+---
+
+## Environment variables
+
+These are only needed when you publish or call APIs that require auth.
+
+| Target | Env var(s) | Notes |
+|--------|------------|-------|
+| npm | `NPM_TOKEN` | Use a granular token with publish rights |
+| NuGet | `NUGET_API_KEY` | Works in CI or locally |
+| GitHub | `GITHUB_TOKEN` / `GH_TOKEN` | For releases/issues/ghcr |
+| PyPI | `PYPI_TOKEN` | If you enable PyPI publishing |
+
+---
+
+## Receipts
+
+Receipts are append-only JSON files written under `receipts/`.
+
+They include:
+
+- commit SHA
+- registry versions
+- URLs
+- SHA-256 hashes of key artifacts
+
+If you like receipts, you can plug this into the receipt factory as the "publishing plugin."
+
+---
+
+## Development
+
+```bash
+npm test
+node scripts/audit.mjs
+```
+
+Smoke tests:
+
+```bash
+node scripts/test-providers.mjs
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/bin/mcpt-publishing.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from "../src/cli/router.mjs";
+run(process.argv);

package/docs/CONTRACT.md

@@ -0,0 +1,109 @@
+# Publishing Contract
+
+## Phase 0 — Audit Only
+
+**Goal:** Make reality visible and reproducible before automating anything.
+
+**Rules:**
+- No publishing
+- No auto-tagging
+- No PR-writing
+- No "fixes" beyond producing the report and the plan
+
+**Output:** For every repo/package, answer:
+- What's published?
+- What's true?
+- What's wrong?
+- What do we do next?
+
+**Deliverables:**
+- `inventory.md` — complete map of all published artifacts
+- `reports/phase-0-audit.md` — drift + metadata + identity report
+- `profiles/` — one profile per shipping repo
+- `schemas/profile.schema.json` — machine-readable profile contract
+
+## Phase 1 — Registry Truth Sync (complete)
+
+- All published npm/NuGet versions tagged in git
+- Metadata fixes published (repo URLs, descriptions, READMEs)
+- GitHub Releases created for front-door packages
+- 7 npm metadata-fix publishes, 25 git tags, 12 GitHub Releases
+
+## Phase 2 — Automated Audit + Storefront (complete)
+
+- `scripts/audit.mjs` — automated drift detection with severity engine
+- Weekly GitHub Action updates a pinned "Publishing Health" issue
+- Front-door NuGet packages get icons + rendered READMEs
+- Release strategy locked (see below)
+
+## Phase 3 — Storefront Professionalism (complete)
+
+- All repos have logo, README header, LICENSE, homepage, topics
+- RED=0, YELLOW=0 across 26 repos
+
+## Phase 5 — Multi-Registry Publishing + GitHub Glue + Receipts (current)
+
+- **Provider plugin system:** `scripts/lib/provider.mjs` base class with `detect()`, `audit()`, `plan()`, `publish()`, `receipt()` methods
+- **Auto-discovery:** `scripts/lib/registry.mjs` scans `providers/*.mjs`, validates interface compliance
+- **Extracted providers:** npm, NuGet, GitHub (context loader) — logic extracted verbatim from audit.mjs
+- **New providers:** PyPI (pypi.org JSON API), GHCR (GitHub Packages API via `gh api`)
+- **Receipt system:** `schemas/receipt.schema.json` + `scripts/lib/receipt-writer.mjs` — immutable JSON receipts at `receipts/publish/<owner>--<name>/<target>/<version>.json`
+- **GitHub Glue:** `scripts/lib/github-glue.mjs` — attaches receipts to releases, updates health issue
+- **Refactored audit.mjs:** thin orchestrator that loads providers, iterates manifest, delegates to providers — output format unchanged
+- Adding a new registry = drop a single `.mjs` file in `scripts/lib/providers/`
+
+### Receipt Schema (v1.0.0)
+
+Required fields: `schemaVersion`, `repo` (owner/name), `target` (npm|nuget|pypi|ghcr), `version`, `packageName`, `commitSha` (40-hex), `timestamp` (ISO 8601), `artifacts[]` (name, sha256, size, url). Optional: `metadata{}`.
+
+### Receipt Immutability
+
+Receipts are append-only. Once `receipts/publish/<slug>/<target>/<version>.json` is written, it cannot be overwritten. The receipt writer enforces this at the filesystem level.
+
+## Registry Truth Policy
+
+Published npm/NuGet versions are **immutable reality**. We never:
+- Unpublish to "fix" a version (npm won't let you anyway)
+- Pretend a published version doesn't exist
+- Override registry state with local state
+
+Instead, we reconcile everything else (tags, releases, source files) to match.
+
+## Drift Categories
+
+| Category | Meaning | Severity |
+|----------|---------|----------|
+| `published-not-tagged` | Registry has version X, repo tag missing | RED |
+| `tagged-not-released` | Tag exists, GitHub Release missing | YELLOW |
+| `source-mismatch` | Source claims version Y, registry latest is X | RED |
+| `stale` | Everything consistent but old | GRAY |
+
+## Remediation Policy
+
+- `published-not-tagged` → add matching `vX.Y.Z` tag
+- `source-mismatch` → reconcile source to registry truth
+- `tagged-not-released` → create GitHub Release (front-door required, internal optional)
+- `stale` → no action unless chosen
+
+## Release Strategy (locked)
+
+### Tag format
+- All packages: `vX.Y.Z` (semver with `v` prefix)
+- Monorepos with multiple packages at the same version: single `vX.Y.Z` tag
+- Monorepos where packages version independently: deferred to Phase 3 (use per-package prefixes)
+
+### Publishing rule
+Every `npm publish` or `dotnet nuget push` MUST have a matching git tag created
+immediately after (or before, if tag-driven). The audit script flags violations as RED.
+
+### Front-door packages
+- Tag required
+- GitHub Release required
+- README must render on registry page
+- Correct repo/project URLs required
+
+### Internal packages
+- Tag required
+- GitHub Release optional
+- README optional (GRAY if missing)
+- Correct repo URL required

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@mcptoolshop/mcpt-publishing",
+  "version": "1.0.0",
+  "description": "Publishing health auditor and receipt factory plugin for MCP Tool Shop packages.",
+  "type": "module",
+  "bin": {
+    "mcpt-publishing": "./bin/mcpt-publishing.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/lib/",
+    "schemas/",
+    "profiles/manifest.json",
+    "profiles/example.json",
+    "logo.png",
+    "docs/CONTRACT.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "audit": "node bin/mcpt-publishing.mjs audit",
+    "audit:json": "node bin/mcpt-publishing.mjs audit --json",
+    "test": "node scripts/test-providers.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {},
+  "keywords": [
+    "mcp",
+    "publishing",
+    "audit",
+    "receipts",
+    "registry",
+    "npm",
+    "nuget",
+    "drift-detection"
+  ],
+  "author": "mcp-tool-shop",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mcp-tool-shop/mcpt-publishing.git"
+  },
+  "homepage": "https://github.com/mcp-tool-shop/mcpt-publishing#readme",
+  "bugs": {
+    "url": "https://github.com/mcp-tool-shop/mcpt-publishing/issues"
+  }
+}

package/profiles/example.json

@@ -0,0 +1,23 @@
+{
+  "$comment": "Example profile showing one NuGet + one npm entry",
+  "repo": {
+    "owner": "mcp-tool-shop-org",
+    "name": "soundboard-maui"
+  },
+  "packages": [
+    {
+      "ecosystem": "nuget",
+      "name": "Soundboard.Client",
+      "audience": "front-door",
+      "versionPolicy": { "truth": "registry", "tagPrefix": "v" },
+      "registryUrl": "https://www.nuget.org/packages/Soundboard.Client"
+    },
+    {
+      "ecosystem": "nuget",
+      "name": "Soundboard.Maui.Audio",
+      "audience": "internal",
+      "versionPolicy": { "truth": "registry", "tagPrefix": "v" },
+      "registryUrl": "https://www.nuget.org/packages/Soundboard.Maui.Audio"
+    }
+  ]
+}

package/profiles/manifest.json

@@ -0,0 +1,49 @@
+{
+  "$comment": "Machine-readable inventory of all published packages. Source of truth for audit.mjs.",
+  "npm": [
+    { "name": "@mcptoolshop/mcpt", "repo": "mcp-tool-shop-org/mcpt", "audience": "front-door" },
+    { "name": "@mcptoolshop/mcp-tool-registry", "repo": "mcp-tool-shop-org/mcp-tool-registry", "audience": "front-door" },
+    { "name": "@mcptoolshop/websketch", "repo": "mcp-tool-shop-org/websketch-cli", "audience": "front-door" },
+    { "name": "@mcptoolshop/websketch-ir", "repo": "mcp-tool-shop-org/websketch-ir", "audience": "front-door" },
+    { "name": "@mcptoolshop/voice-soundboard-mcp", "repo": "mcp-tool-shop-org/mcp-voice-soundboard", "audience": "front-door" },
+    { "name": "@mcptoolshop/voice-soundboard-core", "repo": "mcp-tool-shop-org/mcp-voice-soundboard", "audience": "internal" },
+    { "name": "@mcptoolshop/consensus-os", "repo": "mcp-tool-shop-org/ConsensusOS", "audience": "front-door" },
+    { "name": "@mcptoolshop/synthesis", "repo": "mcp-tool-shop-org/synthesis", "audience": "front-door" },
+    { "name": "@mcptoolshop/prov-engine-js", "repo": "mcp-tool-shop-org/prov-engine-js", "audience": "internal" },
+    { "name": "@mcptoolshop/pathway", "repo": "mcp-tool-shop-org/pathway", "audience": "front-door" },
+    { "name": "@mcptoolshop/file-forge", "repo": "mcp-tool-shop-org/mcp-file-forge", "audience": "front-door" },
+    { "name": "@mcptoolshop/accessibility-suite", "repo": "mcp-tool-shop-org/accessibility-suite", "audience": "front-door" },
+    { "name": "@mcptoolshop/a11y-ci", "repo": "mcp-tool-shop-org/accessibility-suite", "audience": "internal" },
+    { "name": "@mcptoolshop/a11y-evidence-engine", "repo": "mcp-tool-shop-org/a11y-evidence-engine", "audience": "internal", "deprecated": true },
+    { "name": "@mcptoolshop/a11y-mcp-tools", "repo": "mcp-tool-shop-org/a11y-mcp-tools", "audience": "internal", "deprecated": true },
+    { "name": "@mcptoolshop/venvkit", "repo": "mcp-tool-shop-org/venvkit", "audience": "front-door" },
+    { "name": "@mcptoolshop/voice-engine-dsp", "repo": "mcp-tool-shop-org/mcp-voice-engine", "audience": "internal" },
+    { "name": "@mcptoolshop/physics-svg", "repo": "mcp-tool-shop-org/siege-kit", "audience": "internal" },
+    { "name": "@mcptoolshop/promo-kit", "repo": "mcp-tool-shop/mcp-tool-shop", "audience": "internal" }
+  ],
+  "nuget": [
+    { "name": "Soundboard.Client", "repo": "mcp-tool-shop-org/soundboard-maui", "audience": "front-door" },
+    { "name": "Soundboard.Maui.Audio", "repo": "mcp-tool-shop-org/soundboard-maui", "audience": "internal" },
+    { "name": "InControl.Core", "repo": "mcp-tool-shop-org/InControl-Desktop", "audience": "internal" },
+    { "name": "InControl.Inference", "repo": "mcp-tool-shop-org/InControl-Desktop", "audience": "internal" },
+    { "name": "Attestia.Core", "repo": "mcp-tool-shop-org/Attestia-Desktop", "audience": "internal" },
+    { "name": "Attestia.Client", "repo": "mcp-tool-shop-org/Attestia-Desktop", "audience": "internal" },
+    { "name": "Attestia.Sidecar", "repo": "mcp-tool-shop-org/Attestia-Desktop", "audience": "internal" },
+    { "name": "Gov.Protocol", "repo": "mcp-tool-shop-org/build-governor", "audience": "internal" },
+    { "name": "Gov.Common", "repo": "mcp-tool-shop-org/build-governor", "audience": "internal" },
+    { "name": "CursorAssist.Canon", "repo": "mcp-tool-shop-org/CursorAssist", "audience": "internal" },
+    { "name": "CursorAssist.Trace", "repo": "mcp-tool-shop-org/CursorAssist", "audience": "internal" },
+    { "name": "CursorAssist.Engine", "repo": "mcp-tool-shop-org/CursorAssist", "audience": "internal" },
+    { "name": "CursorAssist.Policy", "repo": "mcp-tool-shop-org/CursorAssist", "audience": "internal" },
+    { "name": "MouseTrainer.Domain", "repo": "mcp-tool-shop-org/MouseTrainer", "audience": "internal" },
+    { "name": "MouseTrainer.Simulation", "repo": "mcp-tool-shop-org/MouseTrainer", "audience": "internal" },
+    { "name": "MouseTrainer.Audio", "repo": "mcp-tool-shop-org/MouseTrainer", "audience": "internal" },
+    { "name": "RunForgeDesktop.Core", "repo": "mcp-tool-shop-org/runforge-desktop", "audience": "internal" },
+    { "name": "CodeClone.Domain", "repo": "mcp-tool-shop-org/CodeClone-Desktop", "audience": "internal" },
+    { "name": "LinuxDevTyper.Core", "repo": "mcp-tool-shop-org/linux-dev-typer", "audience": "internal" },
+    { "name": "DevOpTyper.Content", "repo": "mcp-tool-shop-org/meta-content-system", "audience": "internal" },
+    { "name": "VortexKit", "repo": "mcp-tool-shop-org/ScalarScope-Desktop", "audience": "internal" }
+  ],
+  "pypi": [],
+  "ghcr": []
+}

package/schemas/audit-receipt.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mcp-tool-shop/mcpt-publishing/schemas/audit-receipt.schema.json",
+  "title": "Audit Receipt",
+  "description": "Record of a publishing health audit run.",
+  "type": "object",
+  "required": ["schemaVersion", "type", "timestamp", "counts", "totalPackages"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "type": {
+      "type": "string",
+      "const": "audit"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the audit ran"
+    },
+    "counts": {
+      "type": "object",
+      "required": ["RED", "YELLOW", "GRAY", "INFO"],
+      "additionalProperties": false,
+      "properties": {
+        "RED": { "type": "integer", "minimum": 0 },
+        "YELLOW": { "type": "integer", "minimum": 0 },
+        "GRAY": { "type": "integer", "minimum": 0 },
+        "INFO": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "ecosystems": {
+      "type": "object",
+      "description": "Package count per ecosystem audited",
+      "additionalProperties": { "type": "integer" }
+    },
+    "totalPackages": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "reportFiles": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "json": { "type": "string" },
+        "markdown": { "type": "string" }
+      }
+    }
+  }
+}

package/schemas/profile.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mcp-tool-shop/mcpt-publishing/schemas/profile.schema.json",
+  "title": "Publishing Profile",
+  "description": "Declares what a repo publishes, where, and how.",
+  "type": "object",
+  "required": ["repo", "packages"],
+  "properties": {
+    "repo": {
+      "type": "object",
+      "required": ["owner", "name"],
+      "properties": {
+        "owner": {
+          "type": "string",
+          "description": "GitHub org or user (e.g. mcp-tool-shop-org)"
+        },
+        "name": {
+          "type": "string",
+          "description": "GitHub repo name"
+        }
+      }
+    },
+    "packages": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["ecosystem", "name", "audience"],
+        "properties": {
+          "ecosystem": {
+            "type": "string",
+            "enum": ["npm", "nuget", "pypi", "ghcr"]
+          },
+          "name": {
+            "type": "string",
+            "description": "Package name/ID as it appears on the registry"
+          },
+          "audience": {
+            "type": "string",
+            "enum": ["front-door", "internal"],
+            "description": "front-door = meant for strangers; internal = dependency/component"
+          },
+          "versionPolicy": {
+            "type": "object",
+            "properties": {
+              "truth": {
+                "type": "string",
+                "const": "registry",
+                "description": "Always registry — published versions are immutable reality"
+              },
+              "tagPrefix": {
+                "type": "string",
+                "default": "v",
+                "description": "Git tag prefix (e.g. v for v1.0.0)"
+              }
+            }
+          },
+          "registryUrl": {
+            "type": "string",
+            "format": "uri",
+            "description": "Direct link to the registry page"
+          },
+          "notes": {
+            "type": "string",
+            "description": "Anything unusual about this package"
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/publishing-config.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mcp-tool-shop/mcpt-publishing/schemas/publishing-config.schema.json",
+  "title": "Publishing Config",
+  "description": "Configuration for the mcpt-publishing CLI.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "profilesDir": {
+      "type": "string",
+      "default": "profiles",
+      "description": "Path to profiles directory (relative to config file or absolute)"
+    },
+    "receiptsDir": {
+      "type": "string",
+      "default": "receipts",
+      "description": "Path to receipts output directory"
+    },
+    "reportsDir": {
+      "type": "string",
+      "default": "reports",
+      "description": "Path to reports output directory"
+    },
+    "github": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "updateIssue": {
+          "type": "boolean",
+          "default": true,
+          "description": "Update the pinned Publishing Health issue after audit"
+        },
+        "attachReceipts": {
+          "type": "boolean",
+          "default": true,
+          "description": "Attach receipt JSON files to GitHub Releases"
+        }
+      }
+    },
+    "enabledProviders": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [],
+      "description": "Allowlist of provider names. Empty array = all providers enabled."
+    }
+  }
+}