ai-saas-guard 0.36.0 → 0.38.0

package/README.md

@@ -37,6 +37,8 @@ Start with the 30-second copy-paste demo: `npx ai-saas-guard@latest demo --summa
 npx ai-saas-guard@latest scan --root /path/to/your-saas --summary
 ```
 
+For AI-heavy PRs, run it in GitHub Actions to turn auth, billing, data, deploy, and test changes into a reviewer queue before merge.
+
 The output is meant to answer three practical questions before you invite users:
 
 - **Can a real user get access they should not have?** Check auth, tenant ownership, Supabase RLS, and Stripe entitlement paths first.
@@ -168,7 +170,7 @@ For a concise comparison with Semgrep, zizmor, OpenSSF Scorecard, Snyk, and GitH
 | --- | --- | --- |
 | Local CLI | Private code, first local launch review, founder or reviewer workflow | Published on npm; local-first, read-only, no code upload, no LLM calls |
 | GitHub Action | CI review queue, SARIF upload, PR summary artifacts, controlled fail thresholds | Available through `zr9959/ai-saas-guard@v0` and fixed version tags |
-| Hosted GitHub App | Future hosted Check Run experience for selected repositories | Limited trial gate only; not the complete hosted SaaS, not a public hosted scanner |
+| Hosted GitHub App | Future hosted Check Run experience for selected repositories | Limited trial gate with staging ingress, public install-info, compact Check Runs, and cleanup handling; not the complete hosted SaaS, not a public hosted scanner |
 
 ## Quick Start
 
@@ -231,19 +233,19 @@ The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is availab
 | Area | Status |
 | --- | --- |
 | Public GitHub repository | Available |
-| npm CLI | `ai-saas-guard@0.36.0` |
-| GitHub Action | `zr9959/ai-saas-guard@v0` or fixed tag `v0.36.0` |
+| npm CLI | `ai-saas-guard@0.38.0` |
+| GitHub Action | `zr9959/ai-saas-guard@v0` or fixed tag `v0.38.0` |
 | Outputs | Launch decision queue, short summary, terminal, JSON, SARIF, and PR-focused markdown |
 | Project config | `.ai-saas-guard.json` rule toggles, severity overrides, suppressions, and fail thresholds |
 | Privacy model | Local-first, read-only scan commands, no LLM calls, no code upload |
-| Versioned Action tags | `v0.36.0`, `v0` |
-| Current release | `0.36.0` turns Markdown and summary output into a clearer launch decision queue with ranking explanations, reviewer checklists, case-study flow, and local trust/resource statements |
+| Versioned Action tags | `v0.38.0`, `v0` |
+| Current release | `0.38.0` closes more of the hosted GitHub App staging loop with public install guidance, selected-repository Check Run wording, signed installation cleanup, and updated hosted docs/tests |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 | Repository trust hardening | Strict branch protection, Dependabot, CodeQL, fast-check fuzzing, signed release provenance assets, private vulnerability reporting, secret scanning, and push protection |
 | Cloudflare hosted ingress | Deployed at `https://ai-saas-guard-hosted.zr9959.workers.dev`; signed GitHub App webhook delivery and compact Check Run smoke now pass in staging |
 | Hosted GitHub App staging | Private App `ai-saas-guard-hosted` (`3834787`) installed on `zr9959/ai-saas-guard`; hosted operations evidence is in [docs/hosted-operations-evidence.md](docs/hosted-operations-evidence.md) |
 | OpenSSF Best Practices | Passing badge, project `12955`; `.bestpractices.json` remains the conservative evidence record |
-| Next roadmap | v0.36.0 plan is tracked in [docs/v0.36-roadmap.md](docs/v0.36-roadmap.md) |
+| Previous roadmap | v0.36.0 plan is tracked in [docs/v0.36-roadmap.md](docs/v0.36-roadmap.md) |
 
 ## Example Finding
 
@@ -361,7 +363,7 @@ The hosted staging harness is documented in [docs/hosted-staging-harness.md](doc
 
 Deployed worker staging evidence is documented in [docs/hosted-deployed-worker-staging.md](docs/hosted-deployed-worker-staging.md). It exports `createHostedDeployedWorkerStagingEvidenceAutomation`, `createHostedDeployedWorkerStagingEvidenceBundle`, and `evaluateHostedDeployedWorkerStagingReleaseGate` from `ai-saas-guard/hosted/deployed-staging`. It validates safe log samples, then turns public HTTPS health, signed webhook replay, deployed worker cleanup, and external CI/scan/rollback evidence into the hosted release gate for a Node/container read-only checkout worker candidate. It does not deploy cloud resources or claim production hosted exposure.
 
-The first live hosted ingress is deployed on Cloudflare Workers at `https://ai-saas-guard-hosted.zr9959.workers.dev` and documented in [hosted/cloudflare-worker/README.md](hosted/cloudflare-worker/README.md). It exposes `/healthz`, `/github/app/manifest-callback`, and signed `/github/webhook` intake backed by Cloudflare KV. A private staging GitHub App, `ai-saas-guard-hosted`, is installed on `zr9959/ai-saas-guard` with selected-repository access and the first-slice permission contract. The Worker verifies signatures, stores compact pull request identity records, exchanges a scoped installation token, fetches PR file metadata from GitHub, classifies PR-risk hotspots, and publishes a bounded Check Run summary. Current deployed evidence is tracked in [docs/hosted-operations-evidence.md](docs/hosted-operations-evidence.md): health, signed webhook delivery, compact KV records, cleanup, and Check Run publication pass for the staging smoke. The Cloudflare Worker still does not run a full source checkout scan worker or store raw webhook payloads, PR title/body text, raw diffs, source, secrets, checkout paths, or installation tokens.
+The first live hosted ingress is deployed on Cloudflare Workers at `https://ai-saas-guard-hosted.zr9959.workers.dev` and documented in [hosted/cloudflare-worker/README.md](hosted/cloudflare-worker/README.md). It exposes `/healthz`, `/github/app/install-info`, `/github/app/manifest-callback`, and signed `/github/webhook` intake backed by Cloudflare KV. A private staging GitHub App, `ai-saas-guard-hosted`, is installed on `zr9959/ai-saas-guard` with selected-repository access and the first-slice permission contract. The Worker verifies signatures, stores compact pull request identity records, exchanges a scoped installation token, fetches PR file metadata from GitHub, classifies PR-risk hotspots, and publishes a bounded selected-repository hosted check with a review queue and manual proof prompt. Signed installation deletion and repository removal events delete matching compact records. Current deployed evidence is tracked in [docs/hosted-operations-evidence.md](docs/hosted-operations-evidence.md): health, signed webhook delivery, compact KV records, cleanup, and Check Run publication pass in staging. The Cloudflare Worker still does not run a full source checkout scan worker or store raw webhook payloads, PR title/body text, raw diffs, source, secrets, checkout paths, or installation tokens.
 
 The hosted operational release gate is documented in [docs/hosted-operational-release-gate.md](docs/hosted-operational-release-gate.md). It defines the hosted-specific CI, replay, queue, worker cleanup, privacy, monitoring, rollback, and incident-response evidence required before any hosted environment is exposed to users. The pure gate evaluator exported from `ai-saas-guard/hosted/contracts` blocks hosted exposure unless every P0 evidence item is fresh, a container digest is recorded, and release notes avoid pentest, certification, and full-audit claims.
 
@@ -415,7 +417,7 @@ Use `suppressions` for narrower false-positive handling when one rule is noisy o
 
 ## GitHub Action
 
-The repo includes a composite Action. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag such as `v0.36.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
+The repo includes a composite Action. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag such as `v0.38.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard

package/dist/hosted/contracts.js

@@ -485,7 +485,7 @@ export function createHostedCheckRunSummary(input) {
         conclusion,
         output: {
             title: formatCheckRunTitle(totalFindings, conclusion, input.failOnSeverity),
-            summary: `Launch gate: ${launchGate}. Review first: What changed at the launch boundary? Manual proof required before release; it is not a full security audit, pentest, or certification.`,
+            summary: `Launch-risk gate: ${launchGate}. Launch gate: ${launchGate}. Review first: What changed at the launch boundary? Manual proof required before release. This is not an AI reviewer and not a full security audit, pentest, or certification.`,
             text: truncateMarkdown(formatCheckRunMarkdown(report, conclusion, localCliCommand, launchGate), input.maxMarkdownChars)
         },
         annotations: report.evidence.slice(0, MAX_CHECK_RUN_ANNOTATIONS).map((finding) => {
@@ -1146,21 +1146,31 @@ function formatCheckRunMarkdown(report, conclusion, localCliCommand, launchGate)
             ...report.evidence.map((finding) => `| ${escapeMarkdownTableCell(finding.severity)} | ${escapeMarkdownTableCell(finding.ruleId)} | ${escapeMarkdownTableCell(formatFindingLocation(finding))} |`)
         ];
     return [
-        "### AI SaaS Guard",
+        "### AI SaaS Guard Launch-risk gate",
         "",
-        "Review first: verify findings locally before launch. This hosted check is not a full security audit, pentest, or certification.",
+        "Review first: verify findings locally before launch or merge. Not an AI reviewer or full security audit.",
         "",
         `Launch gate: ${launchGate}`,
         `Conclusion: ${conclusion}`,
         `Local CLI: \`${localCliCommand}\``,
-        `Retention: compact report ${report.retentionDays} days; raw source, raw diffs, secrets, and customer payloads are not retained.`,
-        "",
-        "Summary:",
-        ...severityOrder.map((severity) => `- ${capitalize(severity)}: ${report.summaryCounts[severity] ?? 0}`),
+        `Retention: compact report ${report.retentionDays} days; no raw source, diffs, secrets, or customer payloads.`,
         "",
         "Review categories:",
         ...(categories.length === 0 ? ["- None"] : categories.map((category) => `- ${category}`)),
         "",
+        "Verification steps:",
+        "- Review listed files before release or merge.",
+        "- Reproduce locally with the CLI command above.",
+        "- Confirm behavior with app-specific tests.",
+        "",
+        "Launch decision queue:",
+        "- Can a real user get access they should not have?",
+        "- Can the app claim success when something failed?",
+        "- Can launch infrastructure do too much damage?",
+        "",
+        "Summary:",
+        ...severityOrder.map((severity) => `- ${capitalize(severity)}: ${report.summaryCounts[severity] ?? 0}`),
+        "",
         "Files to review first:",
         ...(filesToReview.length === 0 ? ["- None"] : filesToReview.map((file) => `- ${file}`)),
         "",
@@ -1169,11 +1179,6 @@ function formatCheckRunMarkdown(report, conclusion, localCliCommand, launchGate)
         "- Why this auth billing data or deploy decision is safe?",
         "- What manual test proves it fails closed?",
         "",
-        "Verification steps:",
-        "- Review each listed file before release or merge.",
-        "- Reproduce locally with the CLI command above.",
-        "- Treat findings as review prompts; confirm behavior with app-specific tests.",
-        "",
         "Findings:",
         ...findingLines
     ].join("\n");

package/docs/README.zh-CN.md

@@ -165,7 +165,7 @@ Next steps
 | --- | --- | --- |
 | 本地 CLI | 私有代码、本机首次上线 review、founder 或 reviewer 自查 | 已发布到 npm；本地优先、只读、不上传代码、不调用 LLM |
 | GitHub Action | CI 里的 review queue、SARIF、PR summary artifact、可控 fail threshold | 可通过 `zr9959/ai-saas-guard@v0` 或固定版本标签使用 |
-| Hosted GitHub App | 未来面向 selected repositories 的 hosted Check Run 体验 | 目前只是 limited trial gate，不是完整 hosted SaaS，也不是公开 hosted scanner |
+| Hosted GitHub App | 未来面向 selected repositories 的 hosted Check Run 体验 | 当前是 staging ingress，已有公开 install-info、compact Check Run 和 cleanup handling；不是完整 hosted SaaS，也不是公开 hosted scanner |
 
 ## 快速开始
 
@@ -211,24 +211,24 @@ node dist/cli.js scan --root /path/to/your-saas
 
 这个仓库是公开 GitHub 仓库。
 
-CLI 已发布到 npm：`ai-saas-guard@0.36.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.36.0`。
+CLI 已发布到 npm：`ai-saas-guard@0.38.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.38.0`。
 
 | 模块 | 状态 |
 | --- | --- |
 | 公开 GitHub 仓库 | 已可用 |
-| npm CLI | `ai-saas-guard@0.36.0` |
-| GitHub Action | `zr9959/ai-saas-guard@v0` 或固定标签 `v0.36.0` |
+| npm CLI | `ai-saas-guard@0.38.0` |
+| GitHub Action | `zr9959/ai-saas-guard@v0` 或固定标签 `v0.38.0` |
 | 输出格式 | 上线决策队列、短 summary、Terminal、JSON、SARIF 和 PR markdown |
 | 项目配置 | `.ai-saas-guard.json` 支持规则开关、severity 覆盖、suppressions 和 fail threshold |
 | 隐私模型 | 本地优先、只读扫描、不调用 LLM、不上传代码 |
-| 当前版本 | `0.36.0` 将 Markdown 和 summary 输出升级成更清楚的上线决策队列，加入排序解释、reviewer checklist、case-study flow 和本地 trust/resource statement |
-| Action 标签 | `v0.36.0`、`v0` |
+| 当前版本 | `0.38.0` 补齐更多 hosted GitHub App staging 闭环：公开 install-info、selected-repository Check Run 文案、签名 installation cleanup，以及对应 hosted 文档和测试 |
+| Action 标签 | `v0.38.0`、`v0` |
 | npm 发布 | GitHub Actions Trusted Publisher/OIDC，无需长期 npm token |
 | 仓库可信度加固 | 严格 branch protection、Dependabot、CodeQL、fast-check fuzzing、signed release provenance assets、private vulnerability reporting、secret scanning 和 push protection |
-| Cloudflare hosted ingress | 已部署到 `https://ai-saas-guard-hosted.zr9959.workers.dev`；签名 GitHub App webhook delivery 和 compact Check Run staging smoke 已通过 |
+| Cloudflare hosted ingress | 已部署到 `https://ai-saas-guard-hosted.zr9959.workers.dev`；提供 `/github/app/install-info`，签名 GitHub App webhook delivery、compact Check Run 和 installation cleanup staging smoke 已通过 |
 | Hosted GitHub App staging | 私有 App `ai-saas-guard-hosted`（`3834787`）已安装到 `zr9959/ai-saas-guard`；hosted operations evidence 见 [docs/hosted-operations-evidence.md](hosted-operations-evidence.md) |
 | OpenSSF Best Practices | 已获得 passing badge，项目 `12955`；`.bestpractices.json` 继续作为保守证据记录 |
-| 下一版路线 | v0.36.0 计划见 [v0.36-roadmap.md](v0.36-roadmap.md) |
+| 上一版路线 | v0.36.0 计划见 [v0.36-roadmap.md](v0.36-roadmap.md) |
 
 ## 主要命令
 
@@ -379,7 +379,7 @@ GitHub Marketplace wrapper 决策见 [docs/github-marketplace-wrapper-decision.m
 
 ## Hosted GitHub App 设计
 
-当前仓库已经包含未来 Hosted GitHub App 的设计文档、纯契约测试、第一个真实 Cloudflare hosted ingress，以及 Node/container read-only checkout scan runner。私有 staging GitHub App `ai-saas-guard-hosted` 已安装到 `zr9959/ai-saas-guard`，Cloudflare 已配置所需的云端凭据绑定。Worker 代码已经能接收签名 webhook、写入 KV 队列、换取 scoped installation token、读取 GitHub PR file metadata、做 compact PR-risk classification，并发布有长度上限的 Check Run summary；当前端到端 GitHub App webhook delivery smoke 已通过，证据记录在 [docs/hosted-operations-evidence.md](hosted-operations-evidence.md)。Cloudflare ingress 本身仍不是完整 source checkout scan worker。
+当前仓库已经包含未来 Hosted GitHub App 的设计文档、纯契约测试、第一个真实 Cloudflare hosted ingress，以及 Node/container read-only checkout scan runner。私有 staging GitHub App `ai-saas-guard-hosted` 已安装到 `zr9959/ai-saas-guard`，Cloudflare 已配置所需的云端凭据绑定。Worker 代码已经能接收签名 webhook、写入 KV 队列、换取 scoped installation token、读取 GitHub PR file metadata、做 compact PR-risk classification，并发布有长度上限的 selected-repository Check Run summary；`/github/app/install-info` 会返回公开安全的安装说明、权限、事件、隐私边界和卸载说明。签名 installation deletion 和 repository removal 事件会删除匹配的 compact records。当前端到端 GitHub App webhook delivery smoke 已通过，证据记录在 [docs/hosted-operations-evidence.md](hosted-operations-evidence.md)。Cloudflare ingress 本身仍不是完整 source checkout scan worker。
 
 相关文档：
 
@@ -412,7 +412,7 @@ GitHub Marketplace wrapper 决策见 [docs/github-marketplace-wrapper-decision.m
 - Hosted staging deployment planner：`ai-saas-guard/hosted/staging` 导出 `planHostedProviderBinding`、`planHostedStagingDeployment` 和 `planHostedGitHubAppPromotion`，把真实 provider 引用、Node/container deployment plan、hosted operational release-gate evidence 和 GitHub App deployment planning 组合起来；缺少 queue、store、worker sandbox、Check Run publisher、logs、metrics、rollback 或 incident-response 引用时，会阻止 staging exposure 和 production promotion；它本身仍然不会调用云平台、创建 GitHub App 或暴露公开 hosted 服务
 - Hosted staging harness：`ai-saas-guard/hosted/staging-harness` 导出 `createFileBackedHostedStagingHarness`、`createHostedStagingHarnessEvidence`、`createHostedStagingReleaseEvidenceBundle`、`evaluateHostedStagingReleaseEvidenceBundle` 和 `validateHostedLogBoundary`，可以在本地用 file-backed queue、compact report、Check Run request 和 worker sandbox 跑通签名 webhook replay、worker tick 和 cleanup 校验，把 success/failure cleanup probes 与 log-boundary samples 转成 release-gate evidence，并直接执行 hosted release gate 判断；它只是 staging 演练工具，不会调用云平台、创建 GitHub App、写真实 Check Run 或暴露公开 hosted 服务
 - Deployed worker staging evidence：`ai-saas-guard/hosted/deployed-staging` 导出 `createHostedDeployedWorkerStagingEvidenceAutomation`、`createHostedDeployedWorkerStagingEvidenceBundle` 和 `evaluateHostedDeployedWorkerStagingReleaseGate`，先验证 safe log samples，再把 public HTTPS health、signed webhook replay、deployed worker cleanup 以及外部 CI/scan/rollback evidence 转成 hosted release gate evidence；它不会部署云资源，也不会宣称 production hosted exposure
-- Cloudflare hosted ingress：`hosted/cloudflare-worker` 已部署到 `https://ai-saas-guard-hosted.zr9959.workers.dev`，提供 `/healthz`、`/github/app/manifest-callback` 和签名 `/github/webhook` intake；Worker 已具备 compact pull request identity、file/category risk signal 和 Check Run metadata 路径；staging GitHub App ID 为 `3834787`，installation ID 为 `135085075`；真实 GitHub App webhook delivery 和 Check Run smoke 已通过；完整 source checkout worker deployment、monitoring、rollback 和 incident-response evidence 仍需要通过 hosted operational release gate
+- Cloudflare hosted ingress：`hosted/cloudflare-worker` 已部署到 `https://ai-saas-guard-hosted.zr9959.workers.dev`，提供 `/healthz`、`/github/app/install-info`、`/github/app/manifest-callback` 和签名 `/github/webhook` intake；Worker 已具备 compact pull request identity、file/category risk signal、selected-repository Check Run metadata 和签名 installation cleanup 路径；staging GitHub App ID 为 `3834787`，installation ID 为 `135085075`；真实 GitHub App webhook delivery 和 Check Run smoke 已通过；完整 source checkout worker deployment、monitoring、rollback 和 incident-response evidence 仍需要通过 hosted operational release gate
 - Hosted GitHub App limited trial gate：`ai-saas-guard/hosted/contracts` 导出 `createHostedGitHubAppTrialGate`，确保 trial 只作用于 selected repositories，并要求 Check Run publication、compact report、worker cleanup 和 safe log-boundary evidence；它不宣称完整 hosted SaaS 已可用
 - Case-study fixture：`examples/case-study-ai-saas` 和 [case-study-ai-saas.md](case-study-ai-saas.md) 展示一个更接近真实 AI SaaS 的 auth、billing、Supabase、Next/Vercel 和 GitHub Actions 风险组合
 - Resource budget：`createLocalScanResourceBudget` 暴露大仓库本地扫描的保守预算：文件数、单文件字节、总字节、忽略 build/dependency 目录、不上传代码、不调用 LLM

package/docs/github-action.md

@@ -6,6 +6,48 @@ Use `zr9959/ai-saas-guard@v0` for the latest compatible pre-1.0 Action. Use a sp
 
 The Action runs the same local scanner inside the GitHub-hosted runner. It reads the checked-out repository, does not call an LLM, and does not upload source code. For `pr-risk`, always use `actions/checkout` with `fetch-depth: 0` so the base branch comparison is available.
 
+## Copy-paste PR launch gate workflow
+
+Use this when you want one PR job to act as the launch-risk middle layer: Markdown goes to `$GITHUB_STEP_SUMMARY` for reviewers, while SARIF goes to GitHub code scanning for alert tracking. This is not an AI reviewer and it does not approve a PR; it translates trust-boundary changes into a reviewer queue.
+
+```yaml
+name: ai-saas-guard-pr-launch-gate
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  launch-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.2
+        with:
+          fetch-depth: 0
+      - uses: zr9959/ai-saas-guard@v0
+        with:
+          command: pr-risk
+          root: ${{ github.workspace }}
+          base: origin/main
+          config: .ai-saas-guard.json
+          format: markdown
+          output: ai-saas-guard-pr.md
+      - run: cat ai-saas-guard-pr.md >> "$GITHUB_STEP_SUMMARY"
+      - uses: zr9959/ai-saas-guard@v0
+        with:
+          command: scan
+          root: ${{ github.workspace }}
+          config: .ai-saas-guard.json
+          format: sarif
+          output: ai-saas-guard.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: ai-saas-guard.sarif
+```
+
 ## PR Summary
 
 Use markdown when reviewers need a short, evidence-first launch decision queue: risky files, required verification, reviewer checklist, ranking explanation, and suggested PR split.

package/docs/github-app-deployment.md

@@ -89,4 +89,6 @@ The repository can now produce and validate the deployment plan, and a private s
 
 This is now a first-slice staging Worker deployment, not a complete hosted scanner. The Worker code verifies signatures, queues compact pull request identity records, exchanges scoped installation tokens, fetches PR file metadata, classifies PR-risk hotspots, and publishes bounded Check Runs. Current operations evidence is tracked in [hosted-operations-evidence.md](hosted-operations-evidence.md); health, signed webhook delivery, compact KV records, cleanup, and Check Run publication pass in staging. It still does not run full source checkout scan workers inside the Cloudflare Worker, store raw diffs, store source code, or expose a production hosted service.
 
+The Worker also exposes public-safe installation guidance at `https://ai-saas-guard-hosted.zr9959.workers.dev/github/app/install-info`. That response documents the install URL, selected-repository boundary, first-slice permissions, subscribed events, privacy model, and uninstall cleanup wording without returning private keys, webhook secrets, installation tokens, source, diffs, or customer payloads. Signed installation deletion and repository removal events delete matching compact records from KV.
+
 The next deployment stage should wire the hosted service runtime, production adapters, [Node/container app skeleton](hosted-node-container-app.md), and [staging deployment planner](hosted-staging-deployment.md) to a real platform queue, compact report store, GitHub installation authentication, worker isolation layer, Checks API publisher, logs, metrics, rollback, and incident-response evidence.

package/docs/hosted-operations-evidence.md

@@ -6,10 +6,14 @@ Passing these checks does not make the project a pentest, certification, or full
 
 ## Current Evidence
 
-Recorded on 2026-05-24 from the deployed Cloudflare Worker and a temporary no-file-change GitHub PR smoke.
+Recorded on 2026-05-25 from the deployed Cloudflare Worker plus the earlier temporary no-file-change GitHub PR smoke.
 
 | Check | Evidence | Result |
 | --- | --- | --- |
+| Cloudflare Worker health, v0.38.0 | `GET https://ai-saas-guard-hosted.zr9959.workers.dev/healthz` returned `ok: true`, routes including `/github/app/install-info`, `checkRunPublisher: "configured"`, `scannerVersion: "0.38.0"`, and all privacy flags set to false for raw payloads, PR text, source, diffs, secrets, customer payloads, checkout paths, and installation tokens | Passed |
+| Public install guidance, v0.38.0 | `GET https://ai-saas-guard-hosted.zr9959.workers.dev/github/app/install-info` returned the `ai-saas-guard-hosted` install URL, selected-repository boundary wording, first-slice permissions `checks: write`, `contents: read`, `metadata: read`, `pull_requests: read`, subscribed events `pull_request`, `installation`, and `installation_repositories`, uninstall cleanup wording, `scannerVersion: "0.38.0"`, and no private keys, webhook secrets, installation tokens, source, diffs, or customer payloads | Passed |
+| Deployed Worker version, v0.38.0 | `wrangler deploy` uploaded 36.35 KiB / gzip 9.30 KiB and deployed version `5999ccce-c64d-4f3f-96c9-b46cff5a2aed` at `2026-05-25T10:51:30Z` verification time | Passed |
+| Staging KV cleanup, v0.38.0 | `wrangler kv bulk delete` removed 104 old `delivery:` and `scan:` staging records, then `wrangler kv key list --namespace-id fa5344fbd7944de6a776bf8731d58460 --remote` returned `[]` | Passed |
 | Cloudflare Worker health | `GET https://ai-saas-guard-hosted.zr9959.workers.dev/healthz` returned `ok: true`, `checkRunPublisher: "configured"`, `scannerVersion: "0.28.0"`, and all privacy flags set to false for raw payloads, PR text, source, diffs, secrets, customer payloads, checkout paths, and installation tokens | Passed |
 | Deployed Worker version | `wrangler deployments list` showed current version `531d2286-86c6-4327-bfd0-67cad8693c10`, deployed at `2026-05-24T09:01:25.706Z` | Passed |
 | KV cleanup | `wrangler kv key list --namespace-id fa5344fbd7944de6a776bf8731d58460 --remote` returned `[]` after smoke cleanup | Passed |

package/docs/npm-publishing.md

@@ -5,11 +5,11 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current published version: `0.36.0`
+- Current published version: `0.38.0`
 - Next source candidate: none
 - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
 - First npm-published version: `0.1.1`
-- GitHub Release: `v0.36.0`
+- GitHub Release: `v0.38.0`
 - Publish workflow: `.github/workflows/npm-publish.yml`
 - Trusted Publisher: GitHub Actions, `zr9959/ai-saas-guard`, workflow `npm-publish.yml`, allowed action `npm publish`
 - Long-lived npm publish token: not required
@@ -18,7 +18,7 @@
 
 Use GitHub Actions with npm Trusted Publisher/OIDC:
 
-1. Create and review a release tag such as `v0.36.0`.
+1. Create and review a release tag such as `v0.38.0`.
 2. Publish from the GitHub Release or run the `Publish npm` workflow manually with `ref` set to that tag.
 3. Keep `permissions.id-token: write` in the workflow so npm can exchange the GitHub Actions OIDC identity for a short-lived publish credential.
 4. Run `npm publish --access public` from the workflow. Trusted publishing automatically generates provenance for this public package from this public repository.

package/docs/project-handoff.md

@@ -66,7 +66,7 @@ Implemented surfaces:
 - hosted Node/container app skeleton document and helpers for safe health and webhook HTTP ingress, one-job worker ticks, in-memory provider adapters, provider reference validation, and the chosen `node_container` roles `webhook-ingress` and `scan-worker`
 - hosted staging deployment planner document and helpers for provider binding, staging release-gate evidence, Node/container deployment composition, and production GitHub App promotion gating
 - hosted staging harness document and helpers for local signed webhook replay, file-backed queue/report/Check Run artifacts, worker sandbox cleanup verification, and release-gate evidence fixtures without cloud calls
-- live Cloudflare hosted ingress at `https://ai-saas-guard-hosted.zr9959.workers.dev` with `/healthz`, `/github/app/manifest-callback`, signed `/github/webhook` intake, Cloudflare KV storage, private staging GitHub App `ai-saas-guard-hosted` (`3834787`) installed on `zr9959/ai-saas-guard`, Worker code for scoped installation-token exchange, PR file metadata fetching, compact PR-risk classification, and bounded Check Run publishing, plus hosted operations evidence in `docs/hosted-operations-evidence.md`
+- live Cloudflare hosted ingress at `https://ai-saas-guard-hosted.zr9959.workers.dev` with `/healthz`, `/github/app/install-info`, `/github/app/manifest-callback`, signed `/github/webhook` intake, Cloudflare KV storage, private staging GitHub App `ai-saas-guard-hosted` (`3834787`) installed on `zr9959/ai-saas-guard`, Worker code for public-safe install guidance, scoped installation-token exchange, PR file metadata fetching, compact PR-risk classification, bounded selected-repository Check Run publishing, and signed installation deletion/repository removal cleanup, plus hosted operations evidence in `docs/hosted-operations-evidence.md`
 - resource caps for repository text collection, including per-file, total-file, and total-byte scan budgets to reduce worst-case memory use
 - hosted pre-implementation contracts document, hosted compact report fixture, and pure helpers for pull request webhook intake planning, durable scan queue upsert planning, worker read-only scan planning, Check Run publication planning, queue-safe pull request event parsing from trusted GitHub event fields, bounded check-run summary rendering, idempotent queue cleanup planning, worker checkout cleanup planning, retention/deletion cleanup planning, and operational release gate evaluation
 - implementation-ready hosted GitHub App permission contract for required permissions, optional PR comment permissions, selected repository installation, and out-of-scope broad permissions

package/hosted/cloudflare-worker/README.md

@@ -5,11 +5,14 @@ This directory contains the first live hosted ingress for `ai-saas-guard`.
 It is intentionally narrow:
 
 - `GET /healthz` returns public-safe service health.
+- `GET /github/app/install-info` returns public-safe installation guidance, first-slice permissions, subscribed events, privacy boundaries, and uninstall wording.
 - `GET /github/app/manifest-callback` acknowledges the GitHub App manifest redirect without storing the one-time code.
 - `POST /github/webhook` verifies GitHub `sha256` webhook signatures before JSON parsing or storage.
 - Requests over 1 MiB are rejected before JSON parsing or KV writes.
 - Signed `pull_request` events are reduced to trusted GitHub identity fields and stored in Cloudflare KV.
 - When GitHub App bindings are configured, the Worker exchanges a scoped installation token, fetches PR file metadata from GitHub, runs compact PR-risk classification, and publishes a bounded Check Run summary.
+- The Check Run summary names the selected-repository hosted check, the Review queue, and a Manual proof prompt so reviewers know which trust-boundary files to inspect before merge.
+- Signed `installation` deletion events and `installation_repositories` `repositories_removed` events delete matching compact `scan:<installation>:...` records from KV when KV list/delete bindings are available.
 - Duplicate GitHub delivery IDs are accepted idempotently.
 - Responses and KV records do not include raw webhook payloads, PR title/body text, source code, diffs, secrets, customer payloads, checkout paths, or installation tokens.
 
@@ -20,7 +23,7 @@ This Worker is a real hosted ingress with first-slice Check Run publishing code,
 - `HOSTED_EVENTS`: Cloudflare KV namespace for compact delivery and queued scan records.
 - `WEBHOOK_SECRET`: Worker secret matching the GitHub App webhook secret.
 - `GITHUB_APP_PRIVATE_KEY`: Worker secret for the staging GitHub App private key, used only in memory to sign short-lived GitHub App JWTs.
-- `SCANNER_VERSION`: public version string, currently `0.28.0`.
+- `SCANNER_VERSION`: public version string, currently `0.38.0`.
 - `GITHUB_APP_ID`, `GITHUB_APP_SLUG`, `GITHUB_APP_INSTALLATION_ID`: public staging identifiers for the private GitHub App installation.
 
 ## Deployment
@@ -39,6 +42,7 @@ After creating the KV namespace, replace the placeholder namespace ID in `wrangl
 Current public staging endpoint:
 
 - Worker URL: `https://ai-saas-guard-hosted.zr9959.workers.dev`
+- Install-info URL: `https://ai-saas-guard-hosted.zr9959.workers.dev/github/app/install-info`
 - KV namespace binding: `HOSTED_EVENTS`
 - KV namespace ID: `fa5344fbd7944de6a776bf8731d58460`
 - GitHub App slug: `ai-saas-guard-hosted`
@@ -47,6 +51,39 @@ Current public staging endpoint:
 - Installed repository: `zr9959/ai-saas-guard`
 - Mode: signed webhook ingress, compact queueing, PR file metadata classification, and bounded Check Run publishing
 
+## Public Install Guidance
+
+`GET /github/app/install-info` is designed for the first screen a repository admin sees before installation. It returns only public-safe fields:
+
+- install URL for `ai-saas-guard-hosted`
+- first-slice permissions: `checks: write`, `contents: read`, `pull_requests: read`, and `metadata: read`
+- subscribed events: `pull_request`, `installation`, and `installation_repositories`
+- selected-repository boundary and explicit wording that the hosted check is not an AI reviewer, pentest, full audit, or certification
+- uninstall/data deletion wording for compact records
+
+Do not add raw app private keys, webhook secrets, installation tokens, source, diffs, customer payloads, or checkout paths to this response.
+
+## Check Run Shape
+
+The Check Run is intentionally compact. It should answer:
+
+- What changed at a launch-risk boundary?
+- Which files are in the Review queue?
+- What Manual proof should block merge until it passes?
+- What selected-repository permissions did the hosted check use?
+
+The Check Run must not include patch text, source snippets, PR title/body text, secrets, installation tokens, customer data, or private checkout paths.
+
+## Uninstall And Repository Removal
+
+The Worker handles signed GitHub cleanup events, including installation deletion:
+
+- `installation` with action `deleted` deletes compact scan records for the installation.
+- `installation_repositories` with action `removed` deletes compact scan records for removed repository IDs.
+- repeated cleanup is safe because deleting an already-removed compact record is a no-op.
+
+Delivery audit records may remain for the normal KV TTL. They must not contain source, diffs, secrets, customer payloads, PR-authored text, checkout paths, or installation tokens.
+
 ## Release Boundary
 
 Do not expose this as the full product. The hosted operational release gate still requires deployed evidence for Check Run publication, worker cleanup, monitoring, rollback, incident response, dependency and deployment artifact scanning, and GitHub App installation behavior.

package/hosted/cloudflare-worker/src/index.js

@@ -17,6 +17,13 @@ const EVENT_TTL_SECONDS = 60 * 60 * 24 * 30;
 export const MAX_WEBHOOK_PAYLOAD_BYTES = 1024 * 1024;
 const MAX_PR_FILES_PAGES = 3;
 const MAX_PATCH_CHARS_PER_FILE = 20_000;
+const HOSTED_APP_PERMISSIONS = {
+  checks: "write",
+  contents: "read",
+  metadata: "read",
+  pull_requests: "read"
+};
+const HOSTED_APP_EVENTS = ["pull_request", "installation", "installation_repositories"];
 
 const CATEGORY_WEIGHTS = {
   "auth/session": 30,
@@ -38,6 +45,10 @@ export default {
       return jsonResponse(200, createHostedWorkerHealth(env));
     }
 
+    if (request.method === "GET" && url.pathname === "/github/app/install-info") {
+      return jsonResponse(200, createHostedInstallInfo(env));
+    }
+
     if (request.method === "GET" && url.pathname === "/github/app/manifest-callback") {
       return jsonResponse(200, createGitHubAppManifestCallback(url));
     }
@@ -129,6 +140,38 @@ export default {
       });
     }
 
+    if (eventName === "installation" || eventName === "installation_repositories") {
+      let installationPayload;
+      try {
+        installationPayload = JSON.parse(payload);
+      } catch {
+        return jsonResponse(400, {
+          accepted: false,
+          stage: "payload",
+          reason: "invalid_json",
+          deliveryId,
+          privacy: HOSTED_WORKER_PRIVACY
+        });
+      }
+
+      const cleanup = await handleInstallationCleanupEvent({
+        kv: env.HOSTED_EVENTS,
+        deliveryKey,
+        deliveryId,
+        eventName,
+        payload: installationPayload
+      });
+      return jsonResponse(202, {
+        accepted: true,
+        stage: cleanup.cleaned ? "cleanup" : "ignored",
+        reason: cleanup.reason,
+        deliveryId,
+        deletedRecords: cleanup.deletedRecords,
+        shouldCreateCheckRun: false,
+        privacy: HOSTED_WORKER_PRIVACY
+      });
+    }
+
     if (eventName !== "pull_request") {
       await storeJson(env.HOSTED_EVENTS, deliveryKey, {
         deliveryId,
@@ -275,7 +318,7 @@ export function createHostedWorkerHealth(env = {}) {
     ok: true,
     service: "ai-saas-guard-hosted",
     mode: "webhook-ingress",
-    routes: ["/healthz", "/github/app/manifest-callback", "/github/webhook"],
+    routes: ["/healthz", "/github/app/install-info", "/github/app/manifest-callback", "/github/webhook"],
     storage: "cloudflare_kv",
     checkRunPublisher: hasGitHubCheckRunConfig(env) ? "configured" : "not_configured",
     scannerVersion: env.SCANNER_VERSION || "unknown",
@@ -283,6 +326,24 @@ export function createHostedWorkerHealth(env = {}) {
   };
 }
 
+export function createHostedInstallInfo(env = {}) {
+  const slug = stringValue(env.GITHUB_APP_SLUG) ?? "ai-saas-guard-hosted";
+
+  return {
+    ok: true,
+    service: "ai-saas-guard-hosted",
+    installUrl: `https://github.com/apps/${encodeURIComponent(slug)}/installations/new`,
+    permissions: HOSTED_APP_PERMISSIONS,
+    events: HOSTED_APP_EVENTS,
+    boundary:
+      "Install on selected repositories only. The hosted check turns PR trust-boundary changes into a review queue; it is not an AI reviewer, pentest, full audit, or certification.",
+    uninstall:
+      "Uninstall or repository removal deletes compact records for that installation or repository when GitHub sends the signed event. Local CLI use does not depend on hosted installation.",
+    scannerVersion: env.SCANNER_VERSION || "unknown",
+    privacy: HOSTED_WORKER_PRIVACY
+  };
+}
+
 export function createGitHubAppManifestCallback(url) {
   return {
     ok: true,
@@ -387,6 +448,97 @@ async function storeJson(kv, key, value) {
   await kv.put(key, JSON.stringify(value), { expirationTtl: EVENT_TTL_SECONDS });
 }
 
+async function handleInstallationCleanupEvent({ kv, deliveryKey, deliveryId, eventName, payload }) {
+  const cleanup = resolveInstallationCleanup(payload, eventName);
+  await storeJson(kv, deliveryKey, {
+    deliveryId,
+    eventName,
+    accepted: true,
+    reason: cleanup.reason,
+    installationId: cleanup.installationId,
+    repositoryIds: cleanup.repositoryIds,
+    receivedAt: new Date().toISOString()
+  });
+
+  if (!cleanup.cleaned || cleanup.installationId === undefined) {
+    return { ...cleanup, deletedRecords: 0 };
+  }
+
+  const deletedRecords = await deleteCompactRecordsForInstallation({
+    kv,
+    installationId: cleanup.installationId,
+    repositoryIds: cleanup.repositoryIds
+  });
+  return { ...cleanup, deletedRecords };
+}
+
+function resolveInstallationCleanup(payload, eventName) {
+  const installationId = integerValue(payload?.installation?.id);
+  if (installationId === undefined) {
+    return {
+      cleaned: false,
+      reason: "missing_installation_id",
+      installationId,
+      repositoryIds: []
+    };
+  }
+
+  if (eventName === "installation" && payload?.action === "deleted") {
+    return {
+      cleaned: true,
+      reason: "installation_deleted",
+      installationId,
+      repositoryIds: []
+    };
+  }
+
+  if (eventName === "installation_repositories" && payload?.action === "removed") {
+    const repositoryIds = Array.isArray(payload?.repositories_removed)
+      ? payload.repositories_removed.map((repo) => integerValue(repo?.id)).filter((id) => id !== undefined)
+      : [];
+    return {
+      cleaned: repositoryIds.length > 0,
+      reason: repositoryIds.length > 0 ? "repositories_removed" : "no_removed_repositories",
+      installationId,
+      repositoryIds
+    };
+  }
+
+  return {
+    cleaned: false,
+    reason: "installation_event_ignored",
+    installationId,
+    repositoryIds: []
+  };
+}
+
+async function deleteCompactRecordsForInstallation({ kv, installationId, repositoryIds }) {
+  if (typeof kv?.list !== "function" || typeof kv?.delete !== "function") {
+    return 0;
+  }
+
+  let deleted = 0;
+  const prefixes =
+    repositoryIds.length > 0
+      ? repositoryIds.map((repositoryId) => `scan:${installationId}:${repositoryId}:`)
+      : [`scan:${installationId}:`];
+
+  for (const prefix of prefixes) {
+    let cursor;
+    do {
+      const page = await kv.list({ prefix, cursor });
+      for (const key of page.keys ?? []) {
+        if (typeof key?.name !== "string") continue;
+        await kv.delete(key.name);
+        deleted += 1;
+      }
+      cursor = page.list_complete === false ? page.cursor : undefined;
+    } while (cursor);
+  }
+
+  return deleted;
+}
+
 async function runHostedPrRiskCheck({ env, identity, scanKey, scannerVersion }) {
   try {
     await storeJson(env.HOSTED_EVENTS, scanKey, {
@@ -669,19 +821,27 @@ function summarizeFindings(findings) {
 
 function renderCheckRunSummary({ identity, report, scannerVersion }) {
   const lines = [
-    `Review first: ai-saas-guard found ${report.summary.total} PR risk signal(s) for ${identity.repositoryFullName}#${identity.pullRequestNumber}.`,
+    `Launch-risk gate: ai-saas-guard found ${report.summary.total} PR risk signal(s) for ${identity.repositoryFullName}#${identity.pullRequestNumber}. Review first: inspect the listed trust-boundary files before merge.`,
     `Scanner version: ${scannerVersion}.`,
     "",
-    "This is not a pentest, certification, or full security audit. Review the listed files before merge.",
+    "Selected-repository hosted check: this App uses checks:write, contents:read, pull_requests:read, and metadata:read for the installed repository only.",
+    "",
+    "This is not an AI reviewer, pentest, certification, or full security audit. Review the listed files before merge.",
+    "",
+    "Launch decision queue:",
+    "- Can a real user get access they should not have?",
+    "- Can the app claim success when something failed?",
+    "- Can launch infrastructure do too much damage?",
     "",
     "Privacy: this Check Run stores compact file/category signals only. It does not store webhook payload bodies, PR title/body text, diff contents, source, secrets, checkout paths, or installation tokens."
   ];
 
   if (report.topRiskyFiles.length > 0) {
-    lines.push("", "Top files:");
+    lines.push("", "Review queue:");
     for (const file of report.topRiskyFiles.slice(0, 5)) {
       lines.push(`- ${file.path}: ${file.categories.join(", ")} (${file.added}+/${file.removed}-)`);
     }
+    lines.push("", "Manual proof:", "- Review the listed files locally and prove auth, billing, data, deploy, or test changes fail closed before merge.");
   }
 
   if (report.truncated) {

package/hosted/cloudflare-worker/wrangler.jsonc

@@ -7,7 +7,7 @@
     "enabled": true
   },
   "vars": {
-    "SCANNER_VERSION": "0.28.0",
+    "SCANNER_VERSION": "0.38.0",
     "GITHUB_APP_ID": "3834787",
     "GITHUB_APP_SLUG": "ai-saas-guard-hosted",
     "GITHUB_APP_INSTALLATION_ID": "135085075"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-saas-guard",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "Local-first CLI that catches launch blockers in AI-built Next.js/Supabase/Stripe SaaS apps.",
   "readmeFilename": "README.md",
   "type": "module",