diff --git a/README.md b/README.md
index 9e14097..4603762 100644
--- a/README.md
+++ b/README.md
@@ -101,6 +101,31 @@ PRs to trigger checks), and provider API keys enter the picture in exactly two
 optional places: your own eval hook command, and the feed-refresh models-endpoint
 coverage.
 
+## Use it as a GitHub Action
+
+The same gate as a composite action - no npm install, feeds bundled, pinned to
+the `v0` line:
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0 # --changed needs history to diff against the base ref
+- uses: thossullivan/model-eol@v0
+  with:
+    command: check
+    changed: origin/${{ github.base_ref }}
+    days: 90
+    scope: direct
+```
+
+That is the PR gate: fail only when *this* change adds a model that is retired
+or retiring within the threshold. Add `via: aws-bedrock` (or `azure-ai-foundry`)
+to judge by a distributor's clock. The copy-paste version with both gates - PR
+diff plus a weekly full-repository check - is
+[`examples/workflows/model-eol.yml`](examples/workflows/model-eol.yml); the
+same inputs drive `inventory` and `schedule` if CI should export an ML-BOM or a
+retirement calendar instead.
+
 ## Same weights, different clocks
 
 The same model retires on different dates per channel, and a checker that ignores
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..8965490
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,30 @@
+# Security
+
+## Reporting
+
+Report vulnerabilities privately via
+[GitHub private vulnerability reporting](https://github.com/thossullivan/model-eol/security/advisories/new) -
+please don't open a public issue for a security report. Expect a first
+response within a week.
+
+## Supported versions
+
+The latest 0.x release only. There is no backport branch; fixes ship as the
+next patch on npm and move the `v0` action tag.
+
+## Scope
+
+The surface that matters, given zero runtime dependencies:
+
+- The scanner runs against untrusted repository content, so path handling and
+  output escaping (GitHub annotations, badge JSON) are in scope.
+- Feed integrity: `feeds/*.json` are generated from provider pages, and a
+  poisoned feed changes CI verdicts downstream. Feed signing is on the
+  roadmap, not shipped.
+- The bot workflow's privilege split: provider keys live only in the
+  read-only plan/eval job, write tokens only in the publish job. Anything
+  that lets one side reach the other's credentials is a finding.
+
+The checker itself needs no credentials: scanning is static analysis, so a
+report that assumes an API key inside `check.mjs` is out of scope by
+construction.