repoaccess-core 0.2.0

package/README.md

@@ -0,0 +1,149 @@
+# RepoAccess
+
+**Sell access to a private GitHub repo on your own infrastructure, with the payment provider you
+already use.**
+
+A buyer pays, and they're automatically invited to the GitHub team that carries access to your private
+repo. A refund or chargeback revokes it. It runs as a single **Cloudflare Worker** on the **free
+tier**: no server, no SaaS subscription, no per-sale cut.
+
+Use it to sell SaaS boilerplates, starter kits, courses, AI notebooks, private modules, or paid
+community resources. Anything delivered as a repo.
+
+`repoaccess-core` is the free, open-source (AGPL-3.0) core. It ships the **Stripe** adapter plus the
+full grant and revoke engine. **RepoAccess Pro** (see below) adds more payment providers (including
+Merchant-of-Record options) for sellers who can't use Stripe, premium claim-page templates, and support.
+
+## Why this exists
+
+Tools like Polar, Dodo, and GitHub Sponsors also solve "pay, then GitHub access", but they're **billing
+platforms**: you adopt their checkout and they take a per-transaction cut. Two consequences:
+
+- **They're Stripe-bound.** If you're somewhere Stripe isn't available (much of CIS, MENA, Africa,
+  Asia, and beyond), you're locked out.
+- **They own the rail.** You can't bring the provider you already sell with, and you pay a % forever.
+
+RepoAccess is the opposite: a light, single-purpose access-grant worker you self-host and wire to
+**any** webhook-capable provider. Bring your own Stripe, Paddle, Lemon Squeezy, or Gumroad. Keep your
+checkout, your margins, and your region.
+
+## How it works
+
+1. Your provider fires a webhook to your worker on a sale (and on refunds or chargebacks).
+2. The worker **verifies** the signature, **normalizes** the event, and runs a durable **Workflow**.
+3. The buyer lands in the GitHub team that carries your repo. By default they open a one-time **claim
+   link** and enter their GitHub username; if your checkout already collected the username, they're
+   added directly.
+4. On a refund or chargeback (within a 180-day window), access is **revoked** and any pending invite is
+   cancelled.
+
+No "Login with GitHub", no phoning home: GitHub's own invitation _is_ the identity check. Only the real
+account owner can accept it.
+
+## Guided setup (recommended)
+
+The fastest way in is the built-in **setup wizard**. Clone the repo and run it in
+[Claude Code](https://claude.com/claude-code):
+
+```bash
+git clone https://github.com/EdgeKits/repoaccess-core.git
+cd repoaccess-core
+npm install
+claude            # then type: /repoaccess-setup
+```
+
+`/repoaccess-setup` hand-walks you through the entire setup, one verified step at a time: your GitHub
+org and team plus the privacy settings that keep your repos private, the Stripe product and webhook,
+your secrets, deploy, and a live end-to-end test. It edits the config files for you and guides the
+dashboard clicks (no digging through docs), and it never sees your secret values.
+
+**Other agents (Codex, OpenCode, Cursor, ...):** the wizard is agent-agnostic. Claude Code and
+[OpenCode](https://opencode.ai) both expose it as the `/repoaccess-setup` command; for any other coding
+agent, open the cloned repo and ask your agent to follow `docs/setup-wizard.md` - the same shared
+orchestrator the slash commands run.
+
+Rather wire RepoAccess into an existing worker by hand? Use **Compose it yourself** below.
+
+## Compose it yourself
+
+```bash
+npm install repoaccess-core
+```
+
+Compose the adapters you use and pass a typed config:
+
+```ts
+// src/index.ts
+import { createWorker, createAccessWorkflow, ClaimGuard } from 'repoaccess-core'
+import { stripe } from 'repoaccess-core/adapters/stripe'
+import { config } from './repoaccess.config'
+
+// Pass the SAME adapter list to both factories.
+const adapters = [stripe]
+
+export default createWorker({ adapters, config })
+export class AccessWorkflow extends createAccessWorkflow(config, adapters) {}
+export { ClaimGuard }
+```
+
+> `adapters` is optional for hmac-only setups (Stripe), but pass it to both so adding an
+> `api_callback` adapter later just works.
+
+```ts
+// src/repoaccess.config.ts
+import type { RepoAccessConfig } from 'repoaccess-core'
+
+export const config: RepoAccessConfig = {
+  githubOrg: 'your-org',
+  productTeamMap: {
+    stripe: { prod_ABC: { teams: ['pro'], grant_mode: 'username' } },
+    defaults: {
+      teams: [],
+      grant_mode: 'claim',
+      revoke_policy: { mode: 'log_only' },
+    },
+  },
+}
+```
+
+Add the Cloudflare bindings (Workflow, KV, Durable Object), put your secrets (`GITHUB_TOKEN`,
+`STRIPE_WEBHOOK_SECRET`) in `.dev.vars`, and `wrangler deploy`. Full walkthrough:
+[**setup guide**](./docs/setup-guide.md).
+
+## What's in core
+
+- **Stripe** adapter: HMAC-verified `checkout.session.completed`, `charge.refunded`,
+  `charge.dispute.created`.
+- **Grant and revoke** engine: a durable Cloudflare Workflow, idempotent on retried webhooks, GitHub
+  rate-limit backoff, and reconciliation around manual changes.
+- **Claim flow**: a one-time claim link plus a single-flight Durable Object so two submissions can't
+  over-grant. The claim page is a pluggable, seller-brandable template.
+- **Config as code**: a typed config object, no escaped-JSON env vars.
+- **Safe outbound events** (optional): signed `access.*` and `claim.*` webhooks with an SSRF allowlist.
+- Stays on the **Workers free tier**.
+
+## RepoAccess Pro
+
+Core is everything you need to self-host with Stripe. **Pro** is for sellers who need more:
+
+- **More payment providers**: **Paddle** and **Lemon Squeezy** (Merchant-of-Record, with tax handled
+  for you), **Gumroad**, **Razorpay** (India), and **Telegram Stars** (in-Telegram checkout). Sell from
+  the regions, and with the providers, a Stripe-only setup can't reach. More providers are on the way.
+- **Premium claim-page templates**: polished, branded checkout-to-access pages.
+- **Priority support** and quality-of-life extras.
+- One-time license, your own infra, no per-sale cut.
+
+**Pro is launching soon.** For early access and early-bird pricing, join the **Early Birds** list at
+[edgekits.dev](https://edgekits.dev).
+
+## License
+
+AGPL-3.0-or-later. Copyright © 2026 Gary Stupak. See [LICENSE](LICENSE).
+
+If you run a modified RepoAccess as a service for others, the AGPL's network-use terms apply. A
+commercial license (without the copyleft obligations) is available if that doesn't fit:
+[hello@edgekits.dev](mailto:hello@edgekits.dev).
+
+---
+
+RepoAccess is part of [EdgeKits](https://edgekits.dev).

package/docs/agentic-setup-github-core-walkthrough.md

@@ -0,0 +1,139 @@
+# GitHub + Core: the validated manual walkthrough (source for the Agentic Setup wizard)
+
+Purpose: the exact procedure for the **GitHub side** of a self-hosted RepoAccess core: the org, the
+teams that carry repo access, the per-product isolation setting, the org hardening, and the
+fine-grained PAT the worker uses. Run for real (2026-06). Companion to the Stripe walkthrough; together
+they cover the full core setup. This is the base script for the Agentic Setup wizard's GitHub path.
+
+## Legend
+
+- **[USER]** a GitHub dashboard click or value only the user can do. (The agent cannot click GitHub or
+  mint a PAT.) The agent guides precisely and reads back the non-secret results (org slug, team name).
+- **[AGENT]** code or CLI the coding agent does.
+- **[SECRET]** a secret value (the PAT). The user pastes it into `.dev.vars` themselves; the agent must
+  never read, request, or echo it. It references the secret by name only.
+
+## 0. Prerequisites
+
+- A GitHub **organization** you own (Owner role). Personal accounts have no teams, so an org is
+  required; a Free org is fine.
+- The private repo(s) you sell live in this org.
+
+## 1. Create a team per product tier [USER]
+
+- Org, then Teams, then New team. Name it after the tier (e.g. `pro`). One team per product or tier.
+- The worker adds buyers to this team, and the team carries the repo access (Step 2). The worker never
+  adds direct collaborators.
+
+## 2. Attach the private repo(s) to the team [USER]
+
+- Team, then Repositories, then Add repository. Add the repo(s) this tier grants. Give the team `Read`
+  (buyers clone, they do not push) or `Write` if a tier genuinely needs it.
+- Keep the repos **private**.
+
+## 3. Set org Base permissions to `No permission` [USER] (the isolation setting)
+
+- Org, then Settings, then Member privileges, then Base permissions, set to **No permission**, Save.
+- Why it matters: Base permissions are the floor that every org member gets to every repo in the org.
+  Many orgs default to `Read`, which means any buyer of any product could see all your private repos and
+  team scoping buys you nothing. With `No permission`, members get access ONLY through their team(s):
+  buying product A (team A maps to repo A) grants repo A alone; other products' repos stay invisible.
+
+## 4. Harden the org (members are paying customers, not teammates) [USER]
+
+Treat members as untrusted; access comes only through teams. Owners keep full access regardless (these
+toggles restrict members, never you).
+
+**Org, Settings, Member privileges** (each block has its own Save):
+
+- Base permissions, set to No permission (Step 3, the critical one).
+- Repository creation, uncheck Public and Private (members do not create repos).
+- Repository forking, off (no forking private repos into member accounts).
+- Projects base permissions, No access.
+- Pages creation, uncheck Public and Private.
+- App access requests, Disable app access requests.
+- GitHub Apps ("Allow repository admins to install..."), off.
+- Admin repository permissions, off for all: Repository visibility change (else a member-admin could
+  flip a private paid repo to public), Repository deletion and transfer, Issue deletion, Branch renames.
+- Member team permissions, Team creation, off.
+
+**Org, Settings, Authentication security:**
+
+- Do NOT "Require two-factor authentication for everyone". It removes members without 2FA (your buyers)
+  and blocks them from accepting invites. The same risk applies to an IP allow list. Enable 2FA on your
+  own Owner account instead.
+
+**Org, Settings, Third-party Access:**
+
+- OAuth app policy, keep Access restricted (approved apps only).
+- Personal access tokens, Fine-grained tokens, **Allow access via fine-grained PATs** (the worker's
+  `GITHUB_TOKEN` needs this; "Restrict" breaks grants). Optionally Require administrator approval for
+  members' tokens.
+- Token expiry, leave "Fine-grained PATs must expire" on (good hygiene). This means the worker token
+  expires too; see rotation below.
+
+**Optional, Discussions as a feedback channel.** Enabling "Allow users with read access to create
+discussions" gives buyers a built-in Q&A space. Note: discussions in a private repo are visible to
+everyone with access to that repo (your other buyers), so it is a shared space, not private 1:1 support.
+
+## 5. Create the worker's fine-grained PAT [USER] + [SECRET]
+
+First enable fine-grained PATs for the org if needed: Org, Settings, Personal access tokens.
+
+- Your account, Settings, Developer settings, Fine-grained tokens, Generate new token.
+- **Resource owner:** your **org** (not your personal account).
+- **Repository access:** **None** (the token only manages membership; it never touches repos).
+- **Organization permissions:** **Members, Read and write** (and nothing else).
+- **Expiration:** pick a date. The org caps fine-grained PAT lifetime (often 366 days). Note it for
+  rotation.
+- Generate. **[SECRET]** copy the token (`github_pat_…`) and paste it into `.dev.vars` as `GITHUB_TOKEN`
+  yourself. The agent never sees it.
+- If the org requires admin approval for tokens: an **Owner-created token is ready immediately** (no
+  pending step for you, the owner). A member's token would wait for approval.
+
+## 6. Wire it [AGENT] + [SECRET]
+
+- `config.githubOrg` = your org slug. **[AGENT]**
+- `.dev.vars`, `GITHUB_TOKEN` = the PAT (user pastes). **[SECRET]**
+- `config.productTeamMap` maps each product id to the team(s) from Step 1.
+
+## 7. Verify [USER] + watch
+
+- The cleanest verification is the first live grant (see the Stripe walkthrough): a test purchase, the
+  worker adds the buyer to the team, GitHub emails an invite, accept it, the buyer shows under Org,
+  People as a member in the team.
+- Grant fails 401/403: the PAT is missing Members Read and write, or fine-grained PATs are Restricted at
+  the org, or the token is pending approval, or it expired.
+- Grant fails 404 (user not found): the GitHub username does not exist (a buyer typo), not a token
+  problem. In username mode the buyer gets a claim link to self-correct.
+
+## Token rotation (operational)
+
+The worker's `GITHUB_TOKEN` is a fine-grained PAT and **will expire** (the org caps the lifetime).
+Before it does: issue a new token with the same scope (Resource owner org, Repository access none,
+Members Read and write), update the `GITHUB_TOKEN` secret (`wrangler secret put GITHUB_TOKEN`, or
+re-deploy with the new `.dev.vars`), and re-approve it if approval is required. GitHub emails a warning
+before expiry; set a calendar reminder too. If it lapses, grants and revokes stop until you rotate.
+
+## Gotchas
+
+- **New-org invite cap:** 50 invitations per 24h for the first month. Age the org before a big launch.
+- **The invite is the identity check:** the worker sends an invitation only the real account owner can
+  accept. A wrong handle just means the invite sits unaccepted (harmless). There is deliberately no
+  "Login with GitHub".
+- **Org must allow fine-grained PATs** (Step 4, Third-party Access), or grants break.
+- **Do not require org-wide 2FA** (Step 4); it locks out buyers.
+- **Owner token is immediate** even on approval-required orgs.
+
+## Agentic Setup framing (for the wizard build)
+
+- Every GitHub step here is [USER] (the agent cannot click GitHub or mint a PAT). The agent's job is to
+  guide precisely (exact menu paths and toggle values), then read back the non-secret results (org slug,
+  team name) to wire into `config`.
+- **Secret-safe:** the agent tells the user to paste the PAT into `.dev.vars` as `GITHUB_TOKEN`, and
+  never reads, requests, or echoes the token.
+- **Checkpoint:** confirm the team exists and carries the repo, confirm Base permissions = No permission,
+  and confirm the PAT's resource owner and permissions before the user generates it. Verify the whole
+  chain only via the first live grant (Stripe walkthrough).
+- **Order:** do the GitHub side first (org, team, repo attach, base permissions, hardening, PAT) before
+  the worker config and deploy, so `config.githubOrg` and `GITHUB_TOKEN` are ready when you deploy.

package/docs/agentic-setup-stripe-core-walkthrough.md

@@ -0,0 +1,223 @@
+# Stripe + Core: the validated manual walkthrough (source for the Agentic Setup wizard)
+
+Purpose: the exact, end-to-end procedure for standing up a self-hosted RepoAccess **core** worker with
+**Stripe** and proving it live. Every step below was validated for real (in Stripe test mode). This is
+the base script the **Agentic Setup wizard** walks a user through.
+
+## Legend
+
+- **[USER]** a dashboard click or value only the user can do (Stripe / GitHub / Cloudflare web UI). The
+  agent cannot click these; it must guide the user and read back the non-secret results.
+- **[AGENT]** code or CLI the coding agent does (edit files, run `wrangler`).
+- **[SECRET]** a secret value. The user pastes it into `.dev.vars` themselves. The agent must NEVER
+  read, request, or echo a secret value. It only references the secret by name.
+
+## 0. Prerequisites
+
+- A **Stripe account in Test mode** (toggle, top of the dashboard). Do all setup and testing in test
+  mode; no live activation needed for core.
+- A **Cloudflare account** + `wrangler` CLI (`npm i -g wrangler`, then `wrangler login`).
+- A **GitHub org** that owns the private repo(s) you sell, hardened per the setup guide (base
+  permissions `No permission`, fine-grained PAT with Members Read and write).
+- The worker scaffolded: `npm install repoaccess-core`, the entry (`src/index.ts`),
+  `src/repoaccess.config.ts`, and the `wrangler.jsonc` bindings (Workflow + KV + Durable Object), per
+  the setup guide.
+
+## 1. Stripe: create the product [USER]
+
+1. Product catalog, then Create product. Name it (e.g. "My Boilerplate"); set a one-time price.
+   (Stripe renamed this: it is **Product catalog -> Create product**, not the older "Products -> Add
+   product".)
+2. Open the product and copy its **product id** (`prod_…`). You map it to a team in Step 5.
+
+## 2. Stripe: create a Payment Link [USER]
+
+A Payment Link is the no-code checkout. (A coded Checkout Session maps 1:1; see the notes in Step 3.)
+
+1. Payment Links, then New, then **Products or subscriptions**, select your product, quantity 1.
+2. **Options:** leave everything OFF. Do not enable Managed Payments, tax collection, name/address/phone
+   collection, or payment limits. They add friction and complexity you do not need.
+3. **Advanced options**, by grant mode:
+   - **username mode** (the buyer types their GitHub handle at checkout): check **Add custom fields**,
+     Type **Text**, Label **GitHub username**. Do not mark it optional. Stripe auto-derives the field
+     **key** from the label; because the label contains "github", the worker reads it. No manual key is
+     needed (the no-code builder does not expose the key field anyway).
+   - **claim mode** (the buyer gets a one-time claim link after paying): add NO custom field.
+4. **After payment:** Show confirmation page (default).
+5. Create the link and copy its URL (`buy.stripe.com/test_…`).
+
+## 3. Stripe: set `product_id` metadata on the link [USER]
+
+This is the step people miss. The `checkout.session.completed` webhook omits line items, so the worker
+reads the product from **`metadata.product_id`**. The no-code link _builder_ has no metadata field, but
+the **created link's detail page** does:
+
+1. Open the Payment Link's detail page, scroll to **Metadata**, click **Edit metadata**.
+2. Add key `product_id`, value `prod_…` (from Step 1). Save.
+3. Stripe copies a Payment Link's metadata onto every Checkout Session it creates, so it reaches the
+   webhook. (Verified live: the worker read `prod_…` and mapped to the team.)
+
+Coded Checkout Session variant: set `metadata.product_id` when you create the session. If you collect
+the GitHub handle server-side instead of via a custom field, also set `metadata.github_username` (the
+adapter reads metadata first, then the "github" custom field).
+
+## 4. Stripe: create the webhook destination [USER] + [SECRET]
+
+In Stripe's current **Event destinations** flow you select the EVENTS FIRST, then configure the
+destination (endpoint URL). Order:
+
+1. Developers, then Webhooks (Event destinations), then add a destination.
+2. **Select the events FIRST:** exactly these three: `checkout.session.completed`, `charge.refunded`,
+   `charge.dispute.created`. (The current flow asks for events before the URL.)
+3. **Payload style:** if a payload-style choice appears, pick **Snapshot**. The current Event
+   destinations flow may not surface this option (it defaults to the full snapshot payload); if you do
+   not see it, just continue.
+4. **Configure destination - Endpoint URL:** `https://<your-worker>.workers.dev/wh/stripe/<SECRET_PATH>`
+   - `<SECRET_PATH>` is a random hard-to-guess string you generate with
+     `node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"` (cross-platform; node is
+     already required). It is NOT a worker secret (the HMAC signature is the real gate); it only lives in
+     this URL. Keep it in your
+     notes; a handy place is a commented `STRIPE_WEBHOOK_PATH` line in `.dev.vars` (the `.dev.vars.example`
+     template has the slot) so you do not lose it.
+   - `<your-worker>` is known after the first deploy (Step 6). The URL is predictable
+     (`https://<worker-name>.<account>.workers.dev/...`), so you can create the endpoint up front, or
+     come back after deploy.
+5. Create it, then reveal the **Signing secret** (`whsec_…`). **[SECRET]** paste this into `.dev.vars`
+   as `STRIPE_WEBHOOK_SECRET` yourself. The agent never sees it.
+
+## 5. Worker: config [AGENT]
+
+`src/repoaccess.config.ts` (typed object, no escaped JSON):
+
+```ts
+export const config: RepoAccessConfig = {
+  githubOrg: 'your-org',
+  productTeamMap: {
+    stripe: { 'prod_…': { teams: ['pro'], grant_mode: 'username' } }, // or grant_mode: "claim"
+    defaults: {
+      teams: [],
+      grant_mode: 'claim',
+      revoke_policy: { mode: 'log_only' },
+    },
+  },
+}
+```
+
+- Map the **product id** from Step 1 to the GitHub team(s) that carry the repo.
+- `grant_mode`: `username` (use the custom-field handle; auto-falls-back to a claim link if the handle
+  is missing, malformed, or does not exist on GitHub) or `claim` (always send a claim link).
+- `revoke_policy`: `{ mode: "auto_revoke" }` to remove access on refund/chargeback, else
+  `{ mode: "log_only" }`.
+- Keep `defaults.teams` empty unless you intend a catch-all (an unmapped product or a stray webhook
+  falls through to `defaults`).
+
+## 6. Worker: secrets + deploy [USER/SECRET] + [AGENT]
+
+1. `.dev.vars` holds ONLY secrets (the user pastes the values):
+   - `GITHUB_TOKEN` the fine-grained PAT (Members Read and write on the org). **[SECRET]**
+   - `STRIPE_WEBHOOK_SECRET` the `whsec_…` from Step 4. **[SECRET]**
+2. Deploy: `wrangler deploy --secrets-file .dev.vars`. This uploads code plus secrets together; the
+   first deploy creates the worker and prints its `https://<worker>.workers.dev` URL.
+3. Open `/health`, expect `{"status":"ok"}` (confirms the worker booted).
+4. Back in Stripe (Step 4), make sure the webhook Endpoint URL matches the deployed worker URL plus your
+   secret path.
+
+## 7. Test: grant [USER] + watch
+
+1. In a terminal: `wrangler tail <worker-name>` (keep it streaming, started before you pay).
+2. Open the Payment Link, pay with test card **4242 4242 4242 4242**, any future expiry, any CVC, any
+   ZIP, any email.
+   - **username mode:** type a real GitHub handle in the "GitHub username" field. Expect in tail:
+     `POST /wh/stripe/…` then `checkout.session.completed` then a **direct grant**, with `access.granted`
+     and the buyer added to the team. GitHub emails them an invite to accept. No claim page.
+   - **claim mode:** no field. Expect `claim.pending`. The claim link is **not in tail** (the token is
+     redacted for safety). **[AGENT] fetches the token directly from KV and hands the buyer the full
+     clickable link** - PREFERRED: `wrangler kv key get "claim_txn:stripe:<transaction_id>" --binding
+ENTITLEMENTS` returns the token (the `<transaction_id>` is the `pi_...` from the `claim.pending`
+     event), then present `https://<worker>.workers.dev/claim/<token>`. FALLBACK (if the KV read is
+     unavailable): read `claim_url` from the Workflow dashboard `emit:claim.pending` step output. Never
+     make the buyer hunt for it. Open it, enter the handle, get granted.
+3. **Accept the invite [USER] - the worker cannot do this for you.** `access.granted` means the worker
+   **created** the GitHub invitation; it does NOT mean the buyer has joined. GitHub emails the buyer an
+   invitation - open it and **accept** (or accept at `https://github.com/orgs/<org>/invitation`). The
+   buyer becomes a member only after accepting. (Agent: surface this step the moment `access.granted`
+   appears; do NOT silently poll the Workflow or Org, then People for membership beforehand - membership
+   is gated on this human accept, so waiting for it without telling the deployer to accept will hang.)
+4. Verify in GitHub: Org, then People, the buyer is now a member in the right team (it shows only after
+   they accept the invite in step 3).
+
+## 8. Test: refund / revoke [USER]
+
+Do the refund test BEFORE the typo/claim test (Step 9), so revoke runs against a single clean grant from
+Step 7. Refunding first means the same handle is free to reuse on the claim page in Step 9 without
+muddying it - and one GitHub account is enough for the whole run. (Refund last, and the Step-7 handle has
+been granted by two transactions, so a per-transaction revoke looks confusing.)
+
+1. Stripe, then Payments, open the Step-7 test payment, then **Refund payment**, full amount, Refund.
+2. Expect: `POST /wh/stripe/…` (`charge.refunded`), then `access.revoked`, the buyer removed from the
+   team and any pending invite cancelled.
+3. Note: `product_id` is empty on the refund event, but the revoke resolves the policy from the stored
+   grant record, so it still works. `is_full_refund: true` is reliable for Stripe (it compares
+   `amount_refunded` vs `amount`).
+
+## 9. Test: the typo path (username mode) [USER]
+
+1. Pay again, type a **valid-format-but-nonexistent** handle (e.g. `someone-nope-xyz`).
+2. Expect: team-add 404 (user not found), then **not** `access.failed`, but a `grant → claim fallback`,
+   then `claim.pending`. A typo never strands a paying buyer. (Validated live.)
+3. **[AGENT] hands the buyer the claim link** - do not make them find it. PREFERRED: fetch the token from
+   KV with `wrangler kv key get "claim_txn:stripe:<transaction_id>" --binding ENTITLEMENTS` (the
+   `<transaction_id>` is the `pi_...` from `claim.pending`), then present
+   `https://<worker>.workers.dev/claim/<token>`. FALLBACK: the Workflow dashboard `emit:claim.pending`
+   step output (`claim_url`). Open it, enter a real handle (the Step-7 handle is free to reuse now that
+   Step 8 revoked it), and submit.
+4. **Accept the invite [USER].** The claim-page grant creates a NEW GitHub invitation, exactly like Step 7. Open your email and **accept** it (or accept at `https://github.com/orgs/<org>/invitation`); the
+   buyer becomes a member only after accepting. Then verify in GitHub (Org, then People). Do not skip
+   this - the same accept-the-invite step applies to every grant, claim or direct.
+
+## 10. What is normal, and gotchas (so the wizard does not false-alarm)
+
+- **"AccessWorkflow.run - Exception Thrown" / "Cancelled" in tail are benign.** That is how Cloudflare
+  Workflows logs durable step suspension between steps; it appears on fully successful runs too. The
+  proof a run is fine is the Workflow dashboard showing Status: **Completed**, not Failed.
+- **Tail batches a Workflow's logs until the instance settles, so `access.granted` may lag.** Do not
+  treat a not-yet-seen `access.granted` as a failure or sit waiting on the stream. Confirm a grant
+  directly from the KV grant record:
+  `wrangler kv key get "grant:stripe:<transaction_id>" --binding ENTITLEMENTS` (the `<transaction_id>`
+  is the `pi_...`); a returned record means the grant succeeded even if tail has not flushed it yet.
+- **`transaction_id` = `payment_intent`** (`pi_…`), stable across the order and its refund/dispute. (Not
+  the checkout session id, which the refund event lacks.) This is what correlates a refund back to its
+  grant.
+- **Custom-field key** auto-derives from the label and must contain "github" (label "GitHub username"
+  yields a key like `githubusername`). If a valid handle still routes to a claim page, the key did not
+  match: use `metadata.github_username` instead.
+- **KV + workflow naming:** the workflow `name` is account-global; if you run more than one RepoAccess
+  worker on the account, give each a distinct name, or the later deploy reassigns the workflow and
+  breaks the other binding. (Core's is already env-aware - `oss-access-workflow` /
+  `oss-access-workflow-production` - reused idempotently; leave it.) The KV namespace id in
+  `wrangler.jsonc` must be the real one from `wrangler kv namespace create` (a placeholder will not bind).
+  Create it env-correctly so the **title** follows the worker-derived convention -
+  `<worker-name>-ENTITLEMENTS` (sandbox) or `<worker-name>-production-ENTITLEMENTS` (`--env production`):
+  that prefix is what `wrangler` produces when the create picks up the worker `name` and `--env`. A bare
+  `ENTITLEMENTS` title means the prefix did not apply - recreate or rename to the convention. The
+  **binding stays `ENTITLEMENTS`** (the code reads `env.ENTITLEMENTS`); only the namespace title follows
+  the convention.
+- **Test card only in test mode.** `4242 4242 4242 4242` works in test mode; real cards do not.
+
+## Agentic Setup framing (for the wizard build)
+
+Split each step by who can do it, so the wizard hands off cleanly:
+
+- The agent CAN: scaffold and edit `repoaccess.config.ts`, `wrangler.jsonc`, and the `.dev.vars` key
+  names (names only); run `wrangler kv namespace create`, `wrangler deploy`, `wrangler tail`; check
+  `/health`; and read the Workflow dashboard via the user.
+- The agent CANNOT (must guide the user to click): everything in Stripe (product, link, metadata,
+  webhook), the GitHub PAT and org hardening, and accepting GitHub invites.
+- **Secret-safe:** for every `whsec_…` and PAT, the agent tells the user to paste it into `.dev.vars`
+  itself, and must never read, request, or echo a secret value. It references secrets by name only.
+- **Checkpoint and verify after each block** (product, link, metadata, webhook, config, deploy, test)
+  before moving on: confirm the product id, confirm `/health`, confirm `access.granted` in the Workflow
+  run. Do not advance on an unverified step.
+- **Order that minimizes back-and-forth:** GitHub org + PAT, then the worker scaffold + config, then the
+  first deploy (to get the worker URL), then the Stripe product + link + metadata + webhook (URL now
+  known), then re-deploy with the secret, then the test purchases.