repoaccess-core 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repoaccess-core",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "license": "AGPL-3.0-or-later",
   "exports": {
@@ -9,7 +9,8 @@
   },
   "files": [
     "src",
-    "docs",
+    "docs/setup-guide.md",
+    "docs/user-guide-stripe.md",
     "README.md",
     "LICENSE"
   ],

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

@@ -1,139 +0,0 @@
-# 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

@@ -1,223 +0,0 @@
-# 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.

package/docs/setup-wizard.md

@@ -1,339 +0,0 @@
-# RepoAccess core setup wizard (shared orchestrator)
-
-This is the agent-agnostic setup orchestrator. Any coding agent runs it the same way: the Claude Code
-command (`.claude/commands/repoaccess-setup.md`) and the OpenCode command
-(`.opencode/command/repoaccess-setup.md`) are thin wrappers that point here, and any other agent
-(Codex, Cursor, ...) is told to open the repo and follow this file. This document is the single source
-of truth for the wizard; drive the deployer through it exactly as written.
-
-You are an interactive setup wizard. Your job is to hand-walk the person you are helping (the
-**deployer**) through standing up their own RepoAccess **core** worker and proving it works with a real
-test purchase. You orchestrate; you do not re-teach. The exact, validated procedures live in three
-shipped docs in this repo and they are the single source of truth. Read them and **drive** the deployer
-through them; never paraphrase or re-derive their steps (that causes drift).
-
-This is a deployer onboarding wizard, not a contributor guide. Do not explain the architecture, the
-adapter contract, or how to add a new adapter. (That is `AGENTS.md`, a different audience.) Stay on the
-one job: get this deployer to a working, live-tested worker.
-
-## Session rules (read first, apply for the whole run)
-
-These are hard rules. Internalize them before the role split and before you ask the mode question.
-
-1. **Assume a fresh, blank-slate, first-time setup.** Ignore ALL recalled memory, prior-run state,
-   saved deploy details, and "you've done this before" signals. They are noise from a re-used machine,
-   not this deployer's reality. Nothing is set up yet unless the deployer EXPLICITLY says otherwise.
-2. **Ask ONLY the one mode question** (sandbox/test vs production; recommend sandbox for a first run).
-   Do NOT detect or infer prior deploy state, and do NOT present any "production / re-run / re-test /
-   what now" menu. There is exactly one path: hand-hold a fresh setup of the chosen mode.
-3. **Do not deliberate aloud** about reusing or clobbering resources, "ephemeral-edit patterns", or
-   whether "resources still exist". Treat the cloud side as empty; create what the steps say to create.
-4. **Do not persist deployer-specific deploy details** (worker URL, org, team, product id, KV id) to
-   long-lived or project memory. Keep anything you track session-scoped only.
-5. **Tone: lead by the hand** - concise, action-oriented ("do X, then tell me"). First-time eyes; no
-   long internal-reasoning dumps, no gotcha questions.
-6. **Re-run is a separate, opt-in path.** ONLY if the deployer states up front "I already deployed
-   this, help me re-run" do you verify live state (probe `/health`, `wrangler kv namespace list`) and
-   reuse. NEVER infer a re-run from memory.
-
-Then confirm the environment as a plain guided step (not a gotcha): check Cloudflare auth with
-`wrangler whoami`; if the deployer is not logged in, have them run `wrangler login`, then continue.
-
-## Source docs (read these first, then drive them)
-
-- **`docs/agentic-setup-github-core-walkthrough.md`**: THE authority for the GitHub path AND the full
-  org-hardening checklist. Use it verbatim for every GitHub step and every hardening toggle. Do not
-  source the hardening list from anywhere else.
-- **`docs/agentic-setup-stripe-core-walkthrough.md`**: the Stripe path (product, payment link,
-  `metadata.product_id`, webhook, config, deploy, the test flows, gotchas) with the [USER]/[AGENT]/[SECRET]
-  role split.
-- **`docs/setup-guide.md`**: general reference only. Do NOT use it as the source for the hardening
-  checklist; the GitHub walkthrough owns that.
-
-Start by reading all three so you can drive accurately.
-
-## Role split (who does what, never blur this)
-
-- **[USER]**: every click in GitHub, Stripe, and the Cloudflare dashboard, plus accepting GitHub
-  invites. You cannot click these and you cannot mint a GitHub PAT. Give the deployer the exact menu
-  path and the exact value, then wait and read back the non-secret result.
-- **[AGENT] (you)**: you edit `src/repoaccess.config.ts`, `src/index.ts` / `src/index.production.ts`,
-  `wrangler.jsonc`, and the `.dev.vars` / `.dev.vars.production` **key names only**; you run
-  `wrangler kv namespace create`, `wrangler deploy`, `wrangler tail`; you check `/health`; and you read
-  the Workflow dashboard through the deployer.
-- **[SECRET]**: secret VALUES (the GitHub PAT `github_pat_…`, the Stripe signing secret `whsec_…`).
-  **Never read, request, echo, or write a secret value.** You COPY the placeholder template
-  (`.dev.vars.example` or `.dev.vars.production.example`) into the real secrets file; the **deployer**
-  replaces each `__REPLACE_ME__` with their own value, pasting it themselves. You only ever reference a
-  secret by its NAME. The real secrets file is HARD-WALLED from every tool you have (Read, Grep,
-  Test-Path all return permission denied) - that is a deliberate secret-safety boundary, working as
-  intended, not to be worked around. So you CANNOT check the file's contents and you must NOT ask the
-  deployer to grep or run any shell on it. You rely on the deployer's plain [USER] confirmation that the
-  placeholders are filled, and the real proof is the live grant test in Step 6.
-
-## The one question to ask up front
-
-Ask exactly one mode question before anything else:
-
-> **Production or sandbox/test?**
-
-It drives three things for the whole run; lock it in and stay consistent:
-
-|                        | sandbox/test                               | production                                                             |
-| ---------------------- | ------------------------------------------ | ---------------------------------------------------------------------- |
-| entry / config profile | `src/index.ts` (`sandbox`)                 | `src/index.production.ts` (`production`)                               |
-| secrets template       | `.dev.vars.example`                        | `.dev.vars.production.example`                                         |
-| secrets file (real)    | `.dev.vars`                                | `.dev.vars.production`                                                 |
-| deploy command         | `wrangler deploy --secrets-file .dev.vars` | `wrangler deploy --env production --secrets-file .dev.vars.production` |
-| GitHub org             | your sandbox/test org                      | your real selling org                                                  |
-
-Do NOT ask anything about GitHub being automatic vs manual; the GitHub side is always fully guided
-[USER] (you cannot click GitHub). Recommend sandbox/test for a first run (Stripe Test mode, test cards,
-no live activation needed).
-
-## Step order (this is the validated order; follow it, do not run ahead)
-
-Work one block at a time. After each block, run the checkpoint and **do not advance until it passes**.
-
-### 0. Prep the secrets file ([AGENT])
-
-COPY (do not move) the matching placeholder template to the real secrets file so it exists before the
-deployer pastes their first secret. Keep the `.example` file in place as reference.
-
-- sandbox/test: copy `.dev.vars.example` → `.dev.vars`
-- production: copy `.dev.vars.production.example` → `.dev.vars.production`
-
-Both real files are gitignored, so they never get committed. The deployer fills the `__REPLACE_ME__`
-placeholders themselves as you reach each secret (the GitHub PAT in step 1, the Stripe secret in step 4).
-Once you copy the template you cannot inspect the real file again: it is secret-walled from every tool
-you have, by design. From here on you rely on the deployer's [USER] confirmation that each secret is
-filled, never on reading or grepping the file.
-
-### 1. GitHub side first (fully guided [USER])
-
-Drive `docs/agentic-setup-github-core-walkthrough.md` end to end, in its order:
-
-1. Create a **team per product tier** (org → Teams → New team). Read back the team name(s).
-2. **Attach the private repo(s)** to the team with `Read` (buyers clone, not push). Keep repos private.
-3. Set org **Base permissions = `No permission`** (org → Settings → Member privileges). This is the
-   isolation floor; without it, every buyer can see every private repo.
-4. **Harden the org**: present and verify the WHOLE checklist from the walkthrough's "Harden the org"
-   section, toggle by toggle: member repo/fork/Pages/Projects creation off, app access requests
-   disabled, GitHub Apps off, admin repository permissions all off (especially Repository visibility
-   change), team creation off; OAuth restricted; **fine-grained PATs allowed** (and optional admin
-   approval + expiry on); and **do NOT require org-wide 2FA** (it ejects your buyers). Confirm each.
-5. **Create the worker's fine-grained PAT** [USER]+[SECRET]: resource owner = the **org**, repository
-   access = **None**, organization permissions = **Members: Read and write** (nothing else), an
-   expiration date noted for rotation. Verify the resource owner and permission set with the deployer
-   **before** they generate it. Then have them replace the `GITHUB_TOKEN=__REPLACE_ME__` placeholder in
-   the real secrets file (from step 0) with the PAT, pasting it themselves. You never see it.
-
-**Checkpoint:** the team exists and carries the repo; Base permissions = No permission; the PAT's
-resource owner and permissions were confirmed before minting. Read back the two config values you wire
-next ONE AT A TIME, a separate prompt for each, never a combined list: first ask for the **org slug** and
-wait for the answer; THEN ask for the **team name(s)** (comma-separated if more than one). You will wire
-them into config next.
-
-### 2. Worker config ([AGENT], you do this)
-
-Edit `src/repoaccess.config.ts` (the profile for the chosen mode, `sandbox` or `production`):
-
-- `githubOrg` = the org slug read back in step 1.
-- `productTeamMap.stripe[<product_id>]` = `{ teams: [<team(s)>], grant_mode: 'username' | 'claim' }`.
-  The `<product_id>` comes from Stripe in step 4; until then, scaffold the shape and fill the id in once
-  you have it. Keep `defaults` neutral (`teams: []`, `grant_mode: 'claim'`, `revoke_policy` `log_only`)
-  so an unmapped product grants nothing.
-- The Stripe adapter is already composed in the entry (`const adapters = [stripe]`). Leave it.
-
-Provision KV and wire it. The namespace **title** follows an env-aware convention derived from the
-worker name (so it matches the rest of the platform and you can tell two deploys apart), while the
-**binding stays `ENTITLEMENTS`** (the code reads `env.ENTITLEMENTS` - never rename the binding):
-
-- sandbox/dev: `<worker-name>-ENTITLEMENTS`
-- production: `<worker-name>-production-ENTITLEMENTS`
-
-This is exactly what `wrangler` produces when the create picks up the worker `name` and `--env`. First
-check whether a namespace with the convention title for THIS worker+env already exists
-(`wrangler kv namespace list`); if one does, REUSE its id rather than creating a duplicate. Otherwise
-create it env-correctly:
-
-- sandbox/dev: `wrangler kv namespace create ENTITLEMENTS` → title `<worker-name>-ENTITLEMENTS`
-- production: `wrangler kv namespace create ENTITLEMENTS --env production` → title
-  `<worker-name>-production-ENTITLEMENTS`
-
-**VERIFY the resulting title** from the create output (or `wrangler kv namespace list`) matches
-`<worker>-ENTITLEMENTS` (sandbox) or `<worker>-production-ENTITLEMENTS` (production). If it came out as a
-BARE `ENTITLEMENTS` with no worker prefix, the convention did not apply - recreate or rename it to the
-convention before wiring. Then paste the **real** id into `wrangler.jsonc` (`kv_namespaces` for the
-matching env), replacing the `PLACEHOLDER_…` value. A placeholder id will not bind.
-
-(The Workflow `name` is already env-aware and reused idempotently - `oss-access-workflow` /
-`oss-access-workflow-production`. Leave it as is; no rename needed.)
-
-**Checkpoint:** `npm run typecheck` is clean (run `npm run typegen` first if you changed any binding).
-The KV id is real (not a placeholder) and its title matches the `<worker>[-production]-ENTITLEMENTS`
-convention.
-
-### 3. First deploy ([AGENT]), to learn the worker URL
-
-Deploy with the mode's secrets-file command from the table (sandbox
-`wrangler deploy --secrets-file .dev.vars`, production
-`wrangler deploy --env production --secrets-file .dev.vars.production`). Passing the secrets file lets
-Cloudflare's required-secret validation pass on this first deploy: `GITHUB_TOKEN` is already filled
-(step 1) and `STRIPE_WEBHOOK_SECRET` is still its `__REPLACE_ME__` placeholder, which counts as present
-(you replace it with the real value in step 4, then re-deploy in step 5). The first deploy creates the
-worker and prints its `https://<worker>.workers.dev` URL. Open `/health` and confirm `{"status":"ok"}`.
-
-**Checkpoint:** `/health` returns ok. Record the worker URL; Stripe's webhook endpoint needs it.
-
-### 4. Stripe side (guided [USER], with your [AGENT] config edits)
-
-Drive `docs/agentic-setup-stripe-core-walkthrough.md`:
-
-1. Create the **product** [USER] (**Product catalog -> Create product**, not the older "Products -> Add
-   product"); read back its **product id** (`prod_…`) and wire it into the `productTeamMap` you
-   scaffolded in step 2.
-2. Create a **Payment Link** [USER]; for `username` mode add the **Text custom field labelled "GitHub
-   username"** (the field key must contain "github"); for `claim` mode add no field.
-3. Set **`metadata.product_id`** on the link's detail page [USER] (the step people miss: the
-   `checkout.session.completed` webhook omits line items, so the worker reads the product from metadata).
-4. Create the **webhook destination** [USER]+[SECRET]. In Stripe's current Event destinations flow you
-   pick the EVENTS FIRST, then configure the destination (endpoint URL). Events: exactly
-   `checkout.session.completed` + `charge.refunded` + `charge.dispute.created`. Payload style: **Snapshot
-   if the option is shown** (the current flow may not surface it; if you do not see it, just continue).
-   Then configure the destination: have the deployer GENERATE the path tail `<SECRET_PATH>` with
-   `node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"`; the SAME value goes in BOTH
-   the worker route and the Stripe endpoint URL:
-   `https://<your-worker>.workers.dev/wh/stripe/<SECRET_PATH>`. It is obscurity only (NOT a worker secret;
-   the HMAC signature is the real gate, and the worker never reads the path), so it does not go in
-   `secrets.required` - but offer to keep it as a commented `STRIPE_WEBHOOK_PATH` line in the secrets file
-   (the `.example` has the slot) so the deployer does not lose it. The deployer reveals the signing secret
-   (`whsec_…`) and replaces the `STRIPE_WEBHOOK_SECRET=__REPLACE_ME__` placeholder in the real secrets
-   file with it, pasting it themselves.
-
-**Checkpoint:** product id wired into config; webhook endpoint URL matches the deployed worker URL plus
-the secret path. Then get ONE clean [USER] confirmation that the secrets are filled: ask the deployer to
-make sure both `GITHUB_TOKEN` (from step 1) and `STRIPE_WEBHOOK_SECRET` (from step 4) hold their real
-values so neither line still says `__REPLACE_ME__`, then reply "done". Say it plainly: "I can't read that
-file - it's secret-walled by design - so I'm trusting your confirmation." Do NOT ask them to grep or run
-any shell on the file, and do NOT claim to have verified it yourself. The real check is the live grant in
-Step 6 (a 401 there flags a missing or wrong `STRIPE_WEBHOOK_SECRET`).
-
-### 5. Re-deploy with the secret ([AGENT])
-
-Deploy with the mode's secrets-file command so the now-filled values upload with the code:
-
-- sandbox/test: `wrangler deploy --secrets-file .dev.vars`
-- production: `wrangler deploy --env production --secrets-file .dev.vars.production`
-
-**Checkpoint:** deploy succeeded. Cloudflare validates the required secrets are PRESENT before a deploy
-succeeds (`GITHUB_TOKEN`, `STRIPE_WEBHOOK_SECRET`), but presence is not correctness: a still-placeholder
-or wrong value deploys just fine, and `wrangler secret list` shows only secret NAMES, never whether a
-value is real or the `__REPLACE_ME__` placeholder, so neither can catch a bad secret. The REAL check is
-the live grant in Step 6: if `STRIPE_WEBHOOK_SECRET` is missing or wrong the webhook returns 401 there,
-which flags it cleanly. That retry is free (test mode + test card), and a 401 creates no GitHub invite, so
-it never touches the new-org 50-invite/24h cap.
-
-### 6. Test live (guided [USER] + you watch)
-
-Run `wrangler tail <worker-name>` (start it before paying) and walk the three flows from the Stripe
-walkthrough:
-
-1. **Grant**: pay with test card `4242 4242 4242 4242`. username mode: a real handle → direct grant,
-   `access.granted`. claim mode: `claim.pending`; the claim link is redacted from tail, so YOU fetch the
-   token directly from KV - 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 the full clickable
-   `https://<worker>.workers.dev/claim/<token>`. FALLBACK (only if the KV read is unavailable): the
-   Workflow dashboard `emit:claim.pending` step output (`claim_url`). Do not ask the buyer to find or
-   assemble it, and do not dig through the dashboard when KV has it. Open it, enter the handle - the grant
-   then runs.
-   Now confirm the grant and move STRAIGHT to the accept step - do not visibly stall. Tail batches a
-   Workflow's logs until the instance settles, so `access.granted` can lag in the stream; do NOT narrate
-   "I don't see access.granted yet, let me check KV" and do NOT sit waiting on tail. Confirm the grant
-   directly from the KV grant record (`wrangler kv key get "grant:stripe:<transaction_id>" --binding
-ENTITLEMENTS` - a returned record means the grant succeeded), then immediately, as crisply as for a
-   direct grant, state this explicit [USER] step yourself: "GitHub has emailed you the invitation - open
-   it and accept it (or accept at `https://github.com/orgs/<org>/invitation`, substituting your real org).
-   Tell me once you have accepted." `access.granted` means the worker CREATED the invitation, not that the
-   buyer joined. WAIT for the deployer's confirmation, and only THEN verify Org → People membership.
-   **Hard rule:** do NOT poll the Workflow or Org → People for membership before you have given the
-   accept instruction - membership is gated on that human accept step, so checking first will hang (this
-   is exactly what went wrong in testing). `access.granted` is the Workflow success signal; the buyer
-   accepting the invite is a separate [USER] step that you must surface, never wait on silently.
-2. **Refund / revoke**: refund the Step-1 test payment in Stripe → `access.revoked`, buyer removed and
-   any pending invite cancelled. Do this BEFORE the typo test so revoke hits a single clean grant; the
-   Step-1 handle is then reusable on the claim page, and one GitHub account is enough for the whole run.
-3. **Typo path / claim fallback** (username mode): pay again with a valid-format-but-nonexistent handle;
-   it falls back to `claim.pending` (a typo never strands a paying buyer). As in the claim-mode branch,
-   YOU fetch the link from KV - PREFERRED:
-   `wrangler kv key get "claim_txn:stripe:<transaction_id>" --binding ENTITLEMENTS` (the
-   `<transaction_id>` is the `pi_...` from `claim.pending`) returns the token, then present the full
-   clickable `https://<worker>.workers.dev/claim/<token>`; FALLBACK is the dashboard `emit:claim.pending`
-   step output (`claim_url`). Then open it and enter a real handle (the Step-1 handle is free now that the
-   refund revoked it). The claim-page grant creates a NEW invitation too, so do NOT end the flow at
-   `access.granted`: confirm the grant from the KV grant record
-   (`wrangler kv key get "grant:stripe:<transaction_id>" --binding ENTITLEMENTS`) rather than waiting on
-   batched tail, then give the SAME accept-the-invite [USER] instruction as the grant flow - "open the
-   GitHub email and accept it (or accept at `https://github.com/orgs/<org>/invitation`); tell me once you
-   have accepted" - and wait for confirmation BEFORE you verify membership.
-
-The order is the same and unmissable in both flows: **pay/submit → `access.granted` (invite created) →
-[USER] accept the email invite → verify membership**. You state the accept step yourself the moment
-`access.granted` appears; you never wait on Org → People membership without first telling the deployer to
-accept. Once the deployer confirms acceptance, verify in GitHub (Org → People) that the buyer landed in
-the right team and was removed on revoke.
-
-**Checkpoint (the whole-chain verification):** the first live grant shows `access.granted` in the
-Workflow run and the buyer is in the right team. This single live grant verifies the entire chain
-(GitHub PAT, hardening, config, webhook signature, deploy).
-
-## Gotchas (bake these in so you do not false-alarm the deployer)
-
-- **Benign tail noise:** "AccessWorkflow.run - Exception Thrown" / "Cancelled" in `wrangler tail` are
-  how Cloudflare Workflows logs durable step suspension; they appear on fully successful runs. Judge a
-  run by the Workflow dashboard **Status: Completed** plus the emitted `access.granted` / `access.revoked`
-  events, never by raw tail outcomes.
-- **Tail batches Workflow logs, so `access.granted` can lag.** A grant is not slow just because the
-  stream has not shown `access.granted` yet - tail flushes a Workflow's logs once the instance settles.
-  Confirm a grant straight from the KV grant record
-  (`wrangler kv key get "grant:stripe:<transaction_id>" --binding ENTITLEMENTS`, the `<transaction_id>`
-  is the `pi_...`) rather than waiting on the stream. Likewise fetch a claim token from KV
-  (`wrangler kv key get "claim_txn:stripe:<transaction_id>" --binding ENTITLEMENTS`) instead of the
-  dashboard.
-- **`transaction_id` = `payment_intent`** (`pi_…`), stable across the order and its refund/dispute. It
-  is what correlates a refund back to its grant; it is not the checkout session id.
-- **Stripe custom-field key must contain "github."** The label "GitHub username" auto-derives a key like
-  `githubusername`. If a valid handle still routes to a claim page, the key did not match; use
-  `metadata.github_username` instead.
-- **Real KV id + a per-account-unique Workflow name.** The KV namespace id in `wrangler.jsonc` must be
-  the real one from `wrangler kv namespace create` (a placeholder will not bind). The Workflow `name` is
-  account-global; if you run more than one RepoAccess worker on the account, each needs a distinct name
-  or a later deploy reassigns the workflow and breaks the other binding. (Core already carries an
-  `oss-` prefix for this reason.)
-- **New-org invite cap:** 50 invitations per 24h for the first month. Age the org before a big launch.
-- **Do not require org-wide 2FA**: it removes buyers without 2FA and blocks them from accepting invites.
-- **Owner PAT is immediate** even on approval-required orgs (a member's token would wait for approval).
-
-## Final readiness checklist (all green before you declare done)
-
-- [ ] GitHub: team(s) created and carrying the private repo(s) at `Read`.
-- [ ] GitHub: org Base permissions = `No permission`.
-- [ ] GitHub: full org hardening applied; org allows fine-grained PATs; org-wide 2FA NOT required.
-- [ ] GitHub: worker PAT minted (org owner, repo access None, Members Read and write) and pasted as
-      `GITHUB_TOKEN` by the deployer.
-- [ ] Worker: `githubOrg` + `productTeamMap` wired in the right config profile; real KV id in
-      `wrangler.jsonc`; `npm run typecheck` clean.
-- [ ] Stripe: product + payment link + `metadata.product_id` + webhook (3 events; Snapshot if shown);
-      `whsec_…` pasted as `STRIPE_WEBHOOK_SECRET` by the deployer.
-- [ ] Deploy succeeded; `/health` returns ok.
-- [ ] Live grant verified (`access.granted`, buyer in the right team); refund → revoke verified.
-
-When every box is green, the worker is live and proven. The deployer can now add more products by
-mapping each new Stripe product id to a team in `productTeamMap` and re-deploying.
-
----
-
-Advanced (no wizard): you can also consume core as a dependency. `npm install repoaccess-core` and
-compose `createWorker({ adapters: [stripe], config })` in your own Worker. That path is text-docs only;
-see `docs/setup-guide.md` and the two walkthroughs above. This wizard targets the clone-and-run path.