payload-doctor 0.5.4

package/CHANGELOG.md

@@ -0,0 +1,279 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is loosely
+based on [Keep a Changelog](https://keepachangelog.com).
+
+## 0.5.4
+
+Minor polish from a second-pass review. No behaviour change on findings (fixtures still 0 FP).
+
+### Changed
+- `--fix` header now states the file count: `5× in 3 files — a.ts (3), b.ts (2)`.
+
+### Docs
+- Reframed the `returnsTrue()` non-goal as scope demarcation (a hypothetical
+  `always-truthy-expression` check is a separate concern), not risk-avoidance.
+
+## 0.5.3
+
+Closeout of the v0.5.2 code-review feedback (review rated 5/5). No behaviour change on
+real projects (fixtures unchanged: 0 false positives).
+
+### Changed
+- `--fix` groups locations by file (`5× — a.ts (3), b.ts (2), +1 more`) instead of showing
+  only the first occurrence — easier to see where a rule actually fires.
+- Context-specific fix snippets extended beyond the `mass-assignment` pilot to
+  `missing-owner-enforcement` (names the slug and the owner field in a beforeChange stamp),
+  `collection-missing-access` (names the slug), and `reserved-field-name` (names the field).
+
+### Docs
+- Clarified that the self-loop check in cycle detection is intentional: Tarjan places a
+  self-referencing node in a size-1 SCC, so an SCC-size test alone would miss real self-loops.
+- Documented a non-goal: `returnsTrue()` matches only a literal `true`, not constant-folded
+  expressions like `() => (!false)` (vanishingly rare, and folding would add FP risk).
+
+## 0.5.2
+
+Hardening from an external code review (rated 4.8/5, production-ready). All P0 and P1
+items addressed; behaviour of the checks is unchanged on real projects (still 0 FPs on
+the test fixtures). P2 ideas backlogged.
+
+### Fixed (P0)
+- CLI: `--min-score` now validates its argument (must be a number 0–100) and exits with a
+  clear message otherwise, instead of silently using `NaN`.
+- CLI: the ts-morph project setup is wrapped in error handling, and an empty scan (no
+  `.ts/.tsx/.js/.jsx` files under the path) now prints a helpful message and exits 2
+  instead of silently scanning nothing.
+
+### Changed (P1)
+- Cycle detection (`circular-relationship`) now uses Tarjan's SCC — O(V+E) instead of a
+  per-node DFS — so it scales to large relationship graphs. Output is unchanged.
+- `package.json` parsing in `dependency-version-mismatch` is defensively validated
+  (non-object root, non-object `dependencies`, non-string version specs are skipped, never throw).
+- `returnsTrue()` is now AST-based instead of regex: it matches only an *unconditional*
+  `() => true` / `() => { return true }`, so it no longer false-matches on `() => true && x`
+  or a `return true` guarded by an `if`. More precise open-access detection.
+- `--fix` output is now context-aware: each rule shows where it fires (`file:line`, with a
+  count) and checks can supply a context-specific snippet — e.g. `mass-assignment` names the
+  actual field and collection in its suggested field-level `access.create`.
+
+## 0.5.1
+
+Staying on **0.5.x** until the checks run cleanly across many more real projects
+(target: ~10 more real-world runs before any 0.6/1.0). Data-driven against real
+a real 285-file Payload project.
+
+### Added
+- `mass-assignment` (security, error/warning): an **auth** collection with open
+  `create` (public or any authenticated user) and a privileged field
+  (`roles`/`isAdmin`/…) lacking field-level `access.create` and a sanitizing
+  beforeChange hook — a registrant could send `roles: ['admin']` on create.
+  Scoped to auth collections; complements `user-writable-privileged-field` (update path).
+
+### Changed (false-positive & severity tuning from real runs)
+- `local-api-override-access`: server/job context (cron, webhooks, sync/worker/job
+  files, migrations) → `info` (the Local API default is expected there). User-facing
+  routes/actions unchanged.
+- `missing-owner-enforcement`: admin/system-restricted `create` → `info` (system stamps
+  the owner). User-facing create incl. `ownerOrAdmin` stays `warning`.
+- `unsafe-richtext-render`: `warning` → `info` (a static tool can't prove the HTML source
+  is sanitized; it's an audit pointer).
+- `reserved-field-name`: (a) only checks objects inside a real `fields: [...]` array, so
+  raw-query aliases like `{ name: 'm.name' }` are no longer flagged; (b) ignores reserved
+  names on fields nested in `array`/`blocks`/`group` (array rows legitimately carry `id`).
+  Mongo-illegal `.`/`$` still flagged for real fields at any depth.
+- `hook-n-plus-one`: fixed (string-literal) collection → `warning` (batchable N+1);
+  dynamic collection per item → `info` (likely heterogeneous, not trivially batchable).
+- `hardcoded-secret`: in trusted system paths (seed/migrations/scripts) → `info`, so a
+  dev/seed default doesn't tank the score.
+
+### Severity columns
+- The per-rule Summary shows an `Xe/Yw/Zi` breakdown, in the text report and `--json`.
+
+Total: 29 rules (26 per-file in `--list` + duplicate-slug, dependency-version-mismatch,
+circular-relationship cross-file).
+
+Deferred (need real-world validation, likely FP-prone or out of static scope):
+`missing-rate-limit` (limiting often lives in middleware/infra), `exposed-admin-api`
+(admin exposure is a deploy/infra concern, not visible in TS source).
+
+## 0.5.0
+
+### Added
+- **Security depth:**
+  - `auth-weak-config` (warning): auth lockout disabled (`maxLoginAttempts: 0`) or a
+    `tokenExpiration` over 30 days. Only flags explicit weakenings — Payload's defaults
+    are safe, so a *missing* option is not flagged.
+  - `sensitive-data-logged` (warning): a `console.*` call that logs a password/token/
+    secret/apiKey/ssn/cvv value.
+- **Schema & performance hygiene:**
+  - `reserved-field-name` (warning): a field name colliding with Payload-reserved fields
+    (`id`/`_id`/`createdAt`/`updatedAt`/`_status`/…) or illegal in MongoDB (`.`/`$`), and
+    collection slugs colliding with `payload-*` internals. Generic SQL keywords are NOT
+    flagged — the SQL adapter quotes identifiers, so they work.
+  - `excessive-max-depth` (warning): `maxDepth`/`defaultDepth` above 10.
+  - `missing-index-on-filter-field` (info): a commonly-filtered field (email/slug/username/
+    externalId/sku) without `index: true`.
+  - `hook-n-plus-one` (warning): a Local API read (`find`/`findByID`/`findGlobal`) inside a
+    loop or `map`/`forEach`/… callback — the classic N+1.
+  - `circular-relationship` (info, cross-file): relationship/upload fields forming a cycle
+    (A → B → A or self). Cycles are often legitimate, so it's an info reminder to bound `maxDepth`.
+- The per-rule **Summary** now shows a severity breakdown per rule, e.g. `(6e/35w/17i)`,
+  in both the text report and the `--json` `summary` field.
+
+Total: 28 rules (25 per-file in `--list` + duplicate-slug, dependency-version-mismatch,
+circular-relationship as cross-file passes).
+
+## 0.4.1
+
+### Changed
+- **Summary by rule now prints at the TOP** of the report (was at the bottom) — the
+  overview is visible without scrolling past every finding.
+- `side-effect-in-get` is downgraded to `warning` on `unsubscribe`/`opt-out` routes
+  (email one-click unsubscribe is a GET convention), with a note about mail-client
+  prefetch and RFC 8058 List-Unsubscribe-Post. Cron stays `info`, everything else `error`.
+
+### Added
+- `--json` output now includes a `summary` array (per-rule rollup: ruleId, severity,
+  count, files). JSON `schema` bumped to `2`.
+- Documented the score formula in `--help` and the README:
+  `max(0, 100 − 10·errors − 3·warnings)`; info findings don't affect it.
+
+## 0.4.0
+
+### Added
+- Four new static checks:
+  - **`dependency-version-mismatch`** (config, error): reads `package.json` and
+    flags mixed `payload` / `@payloadcms/*` versions — a top cause of mysterious
+    build/runtime breaks. Skips ranges/tags/`workspace:*` it can't compare.
+  - **`relationship-missing-relationTo`** (correctness, error): a `relationship`
+    or `upload` field without `relationTo`.
+  - **`select-without-options`** (correctness, error): a `select`/`radio` field
+    without `options`.
+  - **`duplicate-field-name`** (correctness, error): two fields with the same
+    `name` in the same `fields` array (per-array namespace, no cross-namespace FPs).
+
+## 0.3.1
+
+### Added
+- Four new checks:
+  - **`collection-missing-slug`** (config, error): a collection/global config
+    with `fields` but no `slug`. Only high-confidence configs are flagged
+    (inline `collections:`/`globals:` array elements, or objects typed
+    `CollectionConfig`/`GlobalConfig`), so nested field groups and tabs are safe.
+  - **`hook-missing-return`** (correctness, warning): a transforming hook
+    (`beforeChange`/`beforeValidate`/`beforeRead`/`afterRead`/`beforeDuplicate`)
+    that never returns a value — Payload uses the return value, so the change is
+    silently dropped. Side-effect-only hooks (`afterChange`…) are not flagged.
+  - **`duplicate-slug`** (config, error): the same slug on more than one
+    collection/global (cross-file check).
+  - **`admin-hidden-not-access`** (security, warning): a field with
+    `admin.hidden: true` and no field-level `access` — it is hidden in the Admin
+    UI but still returned by the REST/GraphQL API.
+- **`--fix`**: prints a suggested fix snippet per rule. It never modifies files.
+
+### Changed
+- Sharpened the tagline/description to make clear this is for **Payload CMS**
+  (the framework), not for validating API request/response payloads.
+
+## 0.3.0
+
+### Added
+- **`unsafe-richtext-render` check** (new `rendering` category): flags
+  `dangerouslySetInnerHTML` rendering CMS/rich-text content without visible
+  sanitization — the block-render seam where stored XSS hides. Only fires on
+  content that looks CMS-related (generic React stays out of scope).
+- **`--summary`** flag and an always-on "Summary by rule" rollup (count +
+  distinct files per rule), so large reports don't scroll forever.
+
+### Changed
+- Score weighting: `error=10`, `warning=3`, **`info=0`** (info findings no longer
+  drag the score down).
+- `side-effect-in-get` is downgraded to `info` inside `/cron/` routes (Vercel
+  cron requires GET); a reminder to keep the write idempotent is included.
+
+## 0.2.3
+
+### Changed
+- Repository/author links now point to `github.com/metakraft`.
+
+## 0.2.2
+
+### Fixed
+- A non-existent target path now prints a clear `Path not found:` error and exits
+  with code 2, instead of the ambiguous "No source files found" message.
+
+### Added
+- Scanning a single file (not just a directory) is now supported.
+
+## 0.2.1
+
+### Added
+- Author / maintainer attribution (Leander M. von Kraft — Tierramor Agency) in
+  README, SKILL.md and `package.json`.
+- `package.json` metadata: `author`, `homepage`, `repository`, `bugs`.
+- `SECURITY.md`, `CONTRIBUTING.md`, and a GitHub Actions CI workflow that runs
+  `npm test` on Node 18/20/22.
+- README disclaimer: provided as-is, free and open source, without warranty or
+  support obligation.
+
+## 0.2.0
+
+Tuned against a real-world Payload project to cut false positives.
+
+### Fixed (false positives)
+- **Blocks and globals are no longer mistaken for collections.** A new config
+  classifier uses array position, type annotation (`CollectionConfig` / `Block` /
+  `GlobalConfig`) and file path, and treats anything nested inside a `fields`
+  array as a block. This stops `collection-missing-access`, `open-access-function`,
+  `missing-owner-enforcement`, `user-writable-privileged-field` and
+  `token-field-readable` from firing on blocks.
+- **Public registration** (`create: () => true` on an `auth` collection) is now
+  `info`, not `error`.
+- **Explicit system writes** (`overrideAccess: true` with no `user`, e.g. cron /
+  webhooks) are now `info` instead of `error`; `overrideAccess: true` together
+  with a `user` is still reported by `override-access-true-with-user` (no double
+  reporting).
+
+### Added
+- **Inline suppression** (ESLint-style): `// payload-doctor-disable-next-line`,
+  `// payload-doctor-disable-line`, `// payload-doctor-disable` — optionally
+  scoped to specific rule ids, or all rules when none is given. Suppressed count
+  is shown in text and JSON output.
+- `-V` / `--version` flag; version printed in the report header, `--help`, and as
+  `toolVersion` in JSON.
+- Self-test fixtures for blocks, suppression and system writes.
+
+## 0.1.0
+
+Initial release.
+
+### Checks
+- Access control: `local-api-override-access`, `override-access-true-with-user`,
+  `collection-missing-access`, `open-access-function`, `missing-owner-enforcement`,
+  `user-writable-privileged-field`.
+- Routes: `cron-not-fail-closed`, `side-effect-in-get`, `leaks-error-message`.
+- Config & privacy: `hardcoded-secret`, `wide-open-cors`, `token-field-readable`.
+
+### Tooling
+- 0-100 health score with `great` / `needs-work` / `critical` bands.
+- Text and `--json` output, `--verbose` hints, `--list`, `--min-score`,
+  `--no-exit-code`, `--no-color`. CI-friendly exit codes.
+- Auto-detects `.ts/.tsx/.js/.jsx`; skips `node_modules`, `dist`, `.next`,
+  `build` and treats `migrations/seeds/scripts/tests` as trusted system code.
+
+### False-positive hardening
+- Word-segment matching (camelCase aware) so `hashtags`/`tokenizer` no longer
+  match the `hash`/`token` sensitive-field rule.
+- Tightened the error-leak regex so identifiers like `code.message` /
+  `response.message` are no longer mistaken for `error.message`.
+- `local-api-override-access` skips calls whose options object uses a spread
+  (the spread may carry `overrideAccess: false`).
+- `missing-owner-enforcement` no longer fires when a `beforeValidate`/
+  `beforeChange` hook is present (it may be imported) or the owner field has a
+  `defaultValue`.
+- Dropped speculative field names (`plan`, `tier`) from the privileged-field rule.
+
+### Tests
+- Self-test fixtures: `vulnerable` (must be flagged), `clean` and `tricky`
+  (must produce zero findings). Run with `npm test`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leander M. von Kraft (Tierramor Agency)
+
+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,180 @@
+# payload-doctor
+
+Static **security & correctness linter for [Payload CMS](https://payloadcms.com)** —
+the TypeScript headless CMS. It scans your collections, access control, hooks,
+routes and config for known anti-patterns — the kind that AI coding agents and
+humans alike get wrong — and prints a **0–100 health score** with actionable findings.
+
+> **Note:** this is for **Payload CMS** (the framework). It does *not* inspect or
+> validate API request/response payloads (JSON/XML). If you came looking for that,
+> this isn't it.
+
+Think of it as a `react-doctor` for Payload. One command, no install:
+
+```bash
+npx -y payload-doctor@latest .
+```
+
+## Why
+
+Payload's **Local API bypasses access control by default** (`overrideAccess` is
+`true` unless you set it to `false`). It's the single most expensive footgun in a
+Payload app: a route can authenticate a user and still hand them someone else's
+records, because the collection's `access` functions never run. payload-doctor
+catches that and a dozen related issues before they reach production.
+
+## Usage
+
+```bash
+# scan the current project
+npx -y payload-doctor@latest .
+
+# show fix hints
+npx -y payload-doctor@latest . --verbose
+
+# machine-readable output for CI / dashboards
+npx -y payload-doctor@latest . --json
+
+# big report? show only the per-rule rollup
+npx -y payload-doctor@latest . --summary
+
+# print a suggested fix per rule (never modifies files)
+npx -y payload-doctor@latest . --fix
+
+# fail a CI job if the score drops below a threshold
+npx -y payload-doctor@latest . --min-score 80
+
+# print the version
+npx -y payload-doctor@latest --version
+```
+
+**Recommended workflow:** run it → fix the errors first → re-run and watch the
+score climb. Keep a clean git state before applying fixes.
+
+Score bands: **75–100 great · 50–74 needs work · 0–49 critical.**
+
+The score is `max(0, 100 − 10·errors − 3·warnings)`; `info` findings don't affect
+it. Ten or more errors floor it at `0` by design — once you're in the red, track
+the dropping error/warning counts (and the per-rule summary) to gauge progress
+rather than the score alone.
+
+Exit code is `1` when any `error`-severity finding is present (or the score is
+below `--min-score`), `0` otherwise — drop it straight into CI or a pre-commit
+hook. Use `--no-exit-code` while you're adopting it.
+
+## Suppressing intentional cases
+
+Some findings are deliberate — an OAuth callback that writes on `GET`, a cron
+job using `overrideAccess: true`. Silence them inline, ESLint-style:
+
+```ts
+// payload-doctor-disable-next-line local-api-override-access
+await payload.update({ collection: 'jobs', id, data })
+
+// payload-doctor-disable-line side-effect-in-get
+
+// payload-doctor-disable side-effect-in-get   ← whole file; omit the rule to silence all
+```
+
+Rule names may be written with or without the `payload-doctor/` prefix. The
+number of suppressed findings is reported so suppressions stay visible.
+
+## Checks
+
+| Rule | Category | Severity | What it catches |
+|------|----------|----------|-----------------|
+| `local-api-override-access` | security | error / warning | Local API call without `overrideAccess: false` — access control bypassed |
+| `override-access-true-with-user` | security | error | `overrideAccess: true` while passing a `user` — control skipped on purpose |
+| `collection-missing-access` | security | warning | Collection with no explicit `access` block |
+| `open-access-function` | security | error / info | `access.{create,update,delete}` returns `true` (anyone can write) |
+| `missing-owner-enforcement` | security | warning | User-owned collection that doesn't force ownership on create |
+| `user-writable-privileged-field` | security | error | `roles` / `isAdmin` / … field without field-level `access.update` |
+| `mass-assignment` | security | error/warning | Privileged field settable on create (auth collection, open create, no field `access.create`) |
+| `cron-not-fail-closed` | security | error | Secret/cron guard that is fail-open when the secret is unset |
+| `side-effect-in-get` | correctness | error | `GET` handler performs a write (prefetch / email scanners trigger it) |
+| `leaks-error-message` | security | warning | Internal `error.message` / stack returned to the client |
+| `hardcoded-secret` | security | error | Secret, key or connection string committed as a string literal |
+| `wide-open-cors` | config | warning | CORS set to `'*'` |
+| `token-field-readable` | privacy | warning | Token/hash/secret field exposed via API (no field-level `read`) |
+| `unsafe-richtext-render` | rendering | info | `dangerouslySetInnerHTML` renders CMS/rich-text HTML — review the sink (source may or may not be sanitized) |
+| `collection-missing-slug` | config | error | Collection/global config without a `slug` |
+| `duplicate-slug` | config | error | Same slug on more than one collection/global |
+| `hook-missing-return` | correctness | warning | Transforming hook (`beforeChange`/`afterRead`…) returns nothing |
+| `admin-hidden-not-access` | security | warning | `admin.hidden` field with no field access — still returned by the API |
+| `dependency-version-mismatch` | config | error | Mixed `payload` / `@payloadcms/*` versions in package.json |
+| `relationship-missing-relationTo` | correctness | error | `relationship`/`upload` field without `relationTo` |
+| `select-without-options` | correctness | error | `select`/`radio` field without `options` |
+| `duplicate-field-name` | correctness | error | Two fields with the same `name` in one `fields` array |
+| `auth-weak-config` | security | warning | Auth lockout disabled (`maxLoginAttempts: 0`) or very long `tokenExpiration` |
+| `sensitive-data-logged` | security | warning | `console.*` logs a password/token/secret value |
+| `reserved-field-name` | config | warning | Field/slug collides with a Payload-reserved or Mongo-illegal identifier |
+| `excessive-max-depth` | config | warning | `maxDepth`/`defaultDepth` above 10 |
+| `missing-index-on-filter-field` | config | info | Commonly-filtered field (email/slug/…) without `index: true` |
+| `hook-n-plus-one` | correctness | warning | Local API read inside a loop / `map` (N+1 query) |
+| `circular-relationship` | correctness | info | `relationship`/`upload` fields form a cycle (watch `maxDepth`) |
+
+List them anytime with `npx -y payload-doctor@latest --list`.
+
+> The checks are static heuristics, like any linter. They are tuned for low
+> false-positives, but always review findings in context. Files under
+> `migrations/`, `seeds/`, `scripts/` and tests are treated as trusted system
+> code and skipped for the request-context rules.
+
+## Use with AI coding agents
+
+This repo ships a `SKILL.md`, so it works as an agent skill too:
+
+```bash
+npx skills add https://github.com/metakraft/payload-doctor --skill payload-doctor
+```
+
+Then your agent can run the doctor after generating Payload code, fix the
+flagged issues, and re-run to verify — closing the gap between "AI writes code"
+and "code ships".
+
+## Contributing
+
+A check is a small object implementing the `Check` interface (see `src/types.ts`)
+that receives a `ts-morph` `SourceFile` and returns `Finding[]`. Add yours to the
+relevant file in `src/checks/` and register it in `src/checks/index.ts`. There are
+self-test fixtures in `test/fixtures/` — an intentionally insecure project
+(`vulnerable`), a secure reference (`clean`), and a `tricky` set of legitimate
+patterns that must NOT produce findings (the false-positive guard). Build and run
+the assertion suite with:
+
+```bash
+npm install
+npm test
+```
+
+`npm test` builds the project and asserts that `vulnerable` is flagged while
+`clean` and `tricky` stay silent. Add a fixture whenever you add or change a
+check, and keep the false-positive rate low — a noisy linter gets disabled.
+
+PRs that add checks, reduce false-positives, or add fixtures are welcome.
+
+## Bugs & feature requests
+
+Please use **[GitHub Issues](https://github.com/metakraft/payload-doctor/issues)** —
+there are templates for bug reports (incl. false positives) and new-check requests.
+Open-ended questions and "show & tell" go in
+**[Discussions](https://github.com/metakraft/payload-doctor/discussions)**; suspected
+security issues via a private **Security Advisory** (see `SECURITY.md`). `npm bugs`
+from a project using the package opens the issue tracker directly.
+
+## Author
+
+Leander M. von Kraft — [www.metakraft.de](https://www.metakraft.de)
+Tierramor Agency — AI-native project work.
+
+## Disclaimer
+
+Provided as-is, free and open source, **without warranty or any obligation** —
+no support, no guarantees, no liability. The checks are static heuristics: they
+help, but you remain responsible for reviewing findings and securing your own
+code. Use at your own risk.
+
+## License
+
+[MIT](./LICENSE). Free to use, modify and distribute. No rights reserved beyond
+the attribution the MIT license asks for.

package/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: payload-doctor
+description: Static security and correctness auditor for Payload CMS projects. Use this skill whenever working on Payload CMS access control, collection configuration, hooks, custom endpoints, Next.js route handlers or server actions that read or write Payload data, or before merging any user-data route. Run it after generating or changing Payload code to catch access-control bypasses and related anti-patterns. Trigger on "Payload security", "Payload access control", "overrideAccess", "Local API bypass", "audit Payload", "Payload doctor", "is this Payload collection secure", "check my Payload config", "cron fail closed", "force ownership on create", "side-effect GET", or any request to review the security of a Payload collection, hook, endpoint or route.
+---
+
+# payload-doctor
+
+A CLI that statically audits a Payload CMS project for security and correctness
+anti-patterns and prints a 0-100 health score with file:line findings.
+
+## How to run it
+
+From the project root:
+
+```bash
+npx -y payload-doctor@latest . --verbose
+```
+
+Add `--json` for machine-readable output, `--min-score N` to enforce a threshold
+in CI, `--list` to see all checks.
+
+## Workflow
+
+1. Run the doctor on the Payload project.
+2. Fix `error`-severity findings first, then warnings.
+3. Re-run and confirm the score climbed and the findings are gone.
+4. Keep a clean git state before applying fixes.
+
+Score bands: 75-100 great, 50-74 needs work, 0-49 critical. Exit code is non-zero
+when any error is present.
+
+## What it checks
+
+Access control (Local API `overrideAccess` bypass, open access functions,
+missing collection access, ownership not forced on create, user-writable
+privileged fields), routes (fail-open cron/secret guards, side-effect GETs, error
+leaks), config (hardcoded secrets, wide-open CORS) and privacy (token/hash fields
+readable via API). See README for the full table.
+
+## Interpreting findings
+
+Findings are static heuristics tuned for low false-positives. Always confirm in
+context. The most important rule is `local-api-override-access`: Payload's Local
+API defaults to `overrideAccess: true`, which bypasses collection access control,
+so request-context calls must pass `overrideAccess: false` and `user` (or verify
+ownership manually).
+
+---
+
+By Leander M. von Kraft — www.metakraft.de · Tierramor Agency. MIT licensed, provided as-is without warranty.