Fork-path validation: fix deploy bug, add CONTRIBUTING, patch README

[jeftekhari]

Third and final open-source-readiness blocker. Dry-ran the fork path from a fresh clone, surfaced a real deploy-workflow bug, patched it, then updated docs so the intended flow is actually the documented flow.

What the dry-run revealed

Cloned upstream into /tmp/fresh-fork, ran the README steps. npm install was clean (3s, 127 packages). wrangler dev --local booted and served /health + / correctly against the committed placeholder KV id. Then I checked what .github/workflows/deploy.yml actually does with secrets.

Bug: the ORG_NAME sed uncommented ORG_NAME = "..." but left [vars] commented. Result:

# [vars]
ORG_NAME = "Acme"

ORG_NAME landed at top-level TOML, not inside [vars]. c.env.ORG_NAME in the worker was always undefined for any forker who set the repo variable. Nobody noticed because the upstream runs without ORG_NAME most of the time and the header subtitle silently falls back to empty.

Fix

• Drop the ORG_NAME sed. Pass ORG_NAME (and now GRC_AUDIENCE, for fork-specific OIDC audience scoping) via wrangler deploy --var KEY:VALUE. Binds cleanly regardless of TOML structure, no-op when the repo var is unset.
• Preflight step fails fast with ::error:: when CLOUDFLARE_API_TOKEN or CLOUDFLARE_KV_ID is missing. Previous failure mode was an opaque wrangler auth error or the literal YOUR_KV_NAMESPACE_ID getting sent to the CF API — neither pointed forkers back at their Repo Settings.
• Kept the KV-id sed: narrow string substitution that works correctly.

Docs

• README Setup split into two clearly labelled paths: "Auto-deploy (production)" and "Local-only (development)". Previously intermixed. Documents every secret + variable a forker needs, with links to the Cloudflare dashboard where they're created.
• GRC_AUDIENCE listed as an optional repo variable. Deploy workflow and README now describe the fork-scoping pattern consistently.
• CONTRIBUTING.md (new) — dev loop for scanner and dashboard, .dev.vars instructions for local OIDC bypass, three extension-point walkthroughs (scan rule, policy template, framework). Idempotency rules for templates spelled out so contributors don't accidentally produce noisy commits on every scan. Linked from the README's new Contributing section.
• Checklist items closed: Validate the fork path end-to-end; Contributing guide; How to add scan rules; How to add policy templates.

Side cleanup

npm audit fix bumped hono past the moderate HTML-injection advisory (GHSA-458j-xx4x-4375). Lockfile-only change, no source edits.

Test plan

• Fresh clone → npm install (3s, 127 pkgs, no errors)
• wrangler dev --local boots against placeholder KV id → /health 200 + / renders empty-state 200
• npm run scan -- . post-hono-bump: no behaviour change
• npx tsx scripts/smoke-dashboard.ts post-hono-bump: passes
• After merge: deploy workflow runs on main with real secrets — confirm the workflow logs show the preflight step succeeding, the KV id inject succeeding, and wrangler deploy --var ORG_NAME:... being called with the right value.
• Open the live dashboard after deploy — confirm the header subtitle shows the ORG_NAME (bug fix verification).

Open-source-readiness status after this merge

All three original items closed:

1. ✅ Auth (PR Auth: GitHub OIDC verification on POST /api/report #28)
2. ✅ CI (PR CI: smoke tests for scanner + dashboard render paths #29)
3. ✅ Fork-path validation (this PR)

Remaining softer items are tracked in the checklist — no more blockers for a public announcement.